Short & quick look at filters

If you take a look at single.php you'll notice a few PHP-functions which aren't clear at first sight. Take <?php arras_postheader() ?> as an example. This one is defined in filters.php and tells what to put where in the post header (title, thumbnail, category, etc.).

function arras_postheader() {
    global $post, $id;
    
    if ( is_single() ) {
        if ( is_attachment() ) $postheader .= '<h1 class="entry-title">' . get_the_title() . ' [<a href="' . get_permalink($post->post_parent) . '" rev="attachment">' . get_the_title($post->post_parent) . '</a>]</h1>';
        else $postheader = '<h1 class="entry-title"><a href="' . get_permalink() . '" rel="bookmark">' . get_the_title() . '</a></h1>';
    } else {
        if ( is_attachment() ) $postheader .= '<h2 class="entry-title">' . get_the_title() . ' [<a href="' . get_permalink($post->post_parent) . '" rev="attachment">' . get_the_title($post->post_parent) . '</a>]</h2>';
        else $postheader = '<h2 class="entry-title"><a href="' . get_permalink() . '" rel="bookmark">' . get_the_title() . '</a></h2>';        
    }
    
    if ( !is_page() ) {
        $postheader .= '<div class="entry-info">';
    
        if ( arras_get_option('post_author') ) {
            $postheader .= sprintf( __('<span class="entry-author">By %s</span>', 'arras'), '<address class="author vcard">' . get_the_author() . '</address>' );
        }
        
        if ( arras_get_option('post_date') ) {
            $postheader .= ' &ndash; <abbr class="published" title="' . get_the_time('c') . '">' . get_the_time(get_option('date_format')) . '</abbr>';
        }
        
        if (current_user_can('edit_post')) {
            $postheader .= '<a class="post-edit-link" href="' . get_edit_post_link($id) . '" title="' . __('Edit Post', 'arras') . '">' . __('(Edit Post)', 'arras') . '</a>';
        }
        
        if ( arras_get_option('post_cats') ) {
            $post_cats = array();
            $cats = get_the_category();
            foreach ($cats as $c) $post_cats[] = '<a href="' . get_category_link($c->cat_ID) . '">' . $c->cat_name . '</a>';
            
            $postheader .= sprintf( __('<span class="entry-cat"><strong>Posted in: </strong>%s</span>', 'arras'), implode(', ', $post_cats) );
        }
        
        $postheader .= '</div>';
    }
    
    if ( arras_get_option('single_thumbs') ) {
        $postheader .= '<div class="entry-photo">' . arras_get_thumbnail('featured-slideshow-thumb') . '</div>';
    }
    
    echo apply_filters('arras_postheader', $postheader);
}

Well, that's a bunch of code, isn't it? The most important part here for child theme developers is the last part.
echo apply_filters('arras_postheader', $postheader);

Let's say you want something different in the postheader. You could edit this function or write a function in functions.php of your child theme which will overwrite this. Very simple example, I'm going to put a piece of text there, nothing more.

function change_header() {
            echo 'This is my header'; 
}
add_filter('arras_postheader', 'change_header');

This will result in:

All the stuff (title, author, etc.) is gone and replaced with my text. Advanced users can take advantage of this and create great functions which can overwrite any 'apply filters' used by Arras Theme.

Quick breakdown
add_filter('filter_you_want_to_overwrite', 'function_I_just_wrote')

You can also add $priority & $accepted_args here like with add_action but let's concentrate on the more simple stuff for now.

I'll write something down on the more advanced possibilities later on, but this is the basic idea behind filters.

Advanced look at filters

(more will follow)

Last edited by extatix (2010-05-21 07:44:16)

Quick Guide to Combining Stuff

All the above stuff is nice but how about combining stuff? I'm going to add the <?php wp_list_categories()?> to the single post without editing single.php itself (for the purposeness of clarity I'll keep the php-function I added in the part about templates so there will be two so people won't think I'm cheating

Add a function to the functions.php of your child theme.

function catlist_beneath_author() {
            wp_list_categories();
}
add_action('arras_below_post', 'catlist_beneath_author'); 

I've 'hooked' this action to the 'hook' arras_below_post() which is located right underneath the wp_list_categories() I added in the Templates part.
Result:

What's the use of this I hear you lot thinking, I could have written the function in the first place without the use of a seperate template.

You are right.

But how about this: add a hook of your own in a template.

I'm going to add a hook to single.php which is located between the content and the post author stuff.

First I start with adding an actions.php to my child theme. I made an empty php file and put this in

<?php

function my_first_hook() {
    do_action('my_first_hook');
}

?>

In functions.php I add this at the top of the php right beneath <?php and the text // We're going to add a few functions here

require_once 'actions.php';

I do this to keep it clean. I really should have written my other functions in a seperate php and do a similar thing as I did with actions.php now, it gets messy quick.

Now the the hook in single.php

        <?php arras_postfooter() ?>
        
        <?php my_first_hook() ?>

        <?php if ( arras_get_option('display_author') ) : ?>

This middle part is now added to single.php.

I'm going to add another category list (quite useless, but it's about the idea of course).

function catlist_above_author() {
            wp_list_categories();
}
add_action('my_first_hook', 'catlist_above_author'); 

See, I've hooked it to my_first_hook().

Result:

It's still not very exciting stuff but think about the plugins which will give you a piece of template code which you can play with. Say a ratings-plugin gives you rate_me_now(). Add a function and hook it to your custom hook.

Write a complete new filter to add stuff to your template files. Make new templates like taxonomy.php (I might do that since I use taxonomies). Make hooks in it. Add functions to it. Just awesome stuff can be done.

On and on and on and on. The possibilities are almost limitless. Basically you can make a Child Theme which resembles nothing like Arras Theme but still has the functionalities Arras Theme has got to offer. Or just looks like Arras but works slightly different.

Arras Theme isn't just a theme which works great out of the box (despite the struggles some people have) it also offers great possibilities to customize the hell out of with without touching Arras Theme itself. For that I'm very thankful to Zy.

Last edited by extatix (2010-05-21 08:33:18)

Thanks for the great tips on using child themes effectively. Here's another.

New Widget Areas

It's simple to create new widget areas (sidebars) in your child theme. For this example I'm going to add a widget area (intended for banner advertising, but it could be for any purpose) to appear before the content of every archive-type page. This will involve copying and modifying the archive.php template (see Quick Guide for Templates, above, for an introduction) and adding a few lines to your child theme's functions.php file (see discussion of functions.php, above, for an intro).

archive.php

Here's the relevant section near the beginning of archive.php:

<div id="content" class="section">
<?php arras_above_content() ?>
<?php is_tag(); if ( have_posts() ) : ?>

The first line begins the content div. The second line calls a hook. The third line begins the actual content loop. If you're using the arras_above_content hook, you can decide whether your new widget area belongs before it or after it. In my case I decided to put the widget area after the hook. I'm calling my new widget area "Before Archive" but of course you can call yours whatever you want. Just be sure to use the same name in the template and in the functions file. Here's the new template code:

<div id="content" class="section">
<?php arras_above_content() ?>

    <?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar('Before Archive') ) : ?>
    <!-- optional default content to show when no widget is in this area -->
    <?php endif; ?>

<?php is_tag(); if ( have_posts() ) : ?>

That part tells WP where to put the new widget area.

functions.php

To activate it in your child theme, add the following to your functions.php file:

register_sidebar( array(
    'name' => 'Before Archive',
    'after_widget' => '</div>',
    'before_title' => '<h5 class="widgettitle">',
    'after_title' => '</h5><div class="widgetcontent">'
) );

The only required part is the name parameter, which must match the name in the template file. The rest, in this case, will format a div for the widget area in a way that's consistent with the rest of Arras.

Once you've made these changes you may have to close your browser and re-login to the WP admin area. When you go to Appearance/Widgets you'll see the new widget area listed as a sidebar. You may also find that some of your previously placed widgets have mysteriously migrated to different sidebars than the ones where you originally placed them. If so, just drag them back where they belong. Then you can place any widget(s) you like in the newly created sidebar, and they'll show up where you placed them in the template.

Steve

realy good guide, thx a lot for that i will test a few things when i have the time to. Just one little question, i think you can handle all the code and functions and so on faster then me. i want to make a template as the single.php but i want to add posts of a single category to the end of the page, same style like archive.php and with the arras style options like node based and so on.

do u think u got the time to help me a bit with that?

oh sorry, not the single.php the page.php standardtemplate for a wordpress site and yes with an archive at the bottom.

just one, the thing with pagination is ok i dont need it in this case

ID is 7, but i think when i see the code i will get it a bit more and can do the fine tuning by myself

This works. The main thing is arras_render_posts($args, arras_get_option('archive_display'), 'archive')
The $args stuff. You can give it the stuff you want like any query. See http://codex.wordpress.org/The_Loop

<?php

/* Template Name: Archive Page */

?>

<?php get_header(); ?>

<div id="content" class="section">
<?php arras_above_content() ?>

<?php 
if ( arras_get_option('single_meta_pos') == 'bottom' ) add_filter('arras_postfooter', 'arras_postmeta');
else add_filter('arras_postheader', 'arras_postmeta');
?>


<?php if (have_posts()) : while (have_posts()) : the_post(); ?>
    <?php arras_above_post() ?>
    <div id="post-<?php the_ID() ?>" <?php arras_single_post_class() ?>>
        <?php arras_postheader() ?>
        
        <div class="entry-content">
        <?php the_content( __('<p>Read the rest of this entry &raquo;</p>', 'arras') ); ?>  
        <?php wp_link_pages(array('before' => __('<p><strong>Pages:</strong> ', 'arras'), 
            'after' => '</p>', 'next_or_number' => 'number')); ?>
        </div>
        
        <!-- <?php trackback_rdf() ?> -->
        <?php arras_postfooter() ?>

        <?php if ( arras_get_option('display_author') ) : ?>
        <div class="about-author clearfix">
            <h4><?php _e('About the Author', 'arras') ?></h4>
            <?php echo get_avatar(get_the_author_meta('ID'), 48); ?>
            <?php the_author_meta('description'); ?>
        </div>
        <?php endif; ?>
    </div>
    
    <?php endwhile; else: ?>

<?php arras_post_notfound() ?>

<?php endif; ?>


        <h1 class="home-title">Blabla Archive</h1>
    
    <div id="archive-posts">
    <?php arras_render_posts('cat=7', arras_get_option('archive_display'), 'archive') ?>    
 
    <?php if(function_exists('wp_pagenavi')) wp_pagenavi(); else { ?>
        <div class="navigation clearfix">
            <div class="floatleft"><?php next_posts_link( __('&laquo; Older Entries', 'arras') ) ?></div>
            <div class="floatright"><?php previous_posts_link( __('Newer Entries &raquo;', 'arras') ) ?></div>
        </div>
    <?php } ?>
    </div><!-- #archive-posts -->
    
<?php arras_below_content() ?>
</div><!-- #content -->

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Remember to back it up After the update place it back and it should work

Not a quick one no, 1.3.5 uses arras_get_posts, which is build differently.

Wow. Great series of posts!

I am trying to wrap my head around some of this...

I would like to tweak how the headers look for posts excerpts on the homepage. My goal is to add the author's name below the title. After some searching and fiddling I made the changes to a copy of the tapestries.php in the Library folder of the Arras theme. My hope was that I could then copy that file to a Library folder of my child theme and have the changes show up. No luck. So I started exploring and came upon these great tutorials.

So. I have the changes I want, but I am struggling to figure out which hooks or filters I can tweak and what part of them I need to tweak to get what I want to show up. For example I would like the following code to be displayed instead of the current code for the Per Line tapestry:

/**
 * Per Line tapestry callback function.
 * @since 1.4.3
 */
if (!function_exists('arras_tapestry_line')) {
    function arras_tapestry_line($query, $page_type) {
        echo '<ul class="hfeed posts-line clearfix">';
        while ($query->have_posts()) {
            $query->the_post();
            ?>
            <li <?php arras_post_class() ?>>
            <?php if(!is_archive()) : ?>
                <span class="entry-cat">
                    <?php $cats = get_the_category(); 
                    if (arras_get_option('news_cat')) echo $cats[1]->cat_name;
                    else echo $cats[0]->cat_name; ?>
                </span>
                <?php endif ?>
                
                <h3 class="entry-title"><a rel="bookmark" href="<?php the_permalink() ?>" title="<?php printf( __('Permalink to %s', 'arras'), get_the_title() ) ?>"><?php the_title() ?></a> | By <?php the_author_posts_link(); ?></h3>
                <span class="entry-comments"><?php comments_number() ?></span>
            </li>
            <?php
        }
        echo '</ul><!-- .posts-line -->';
    }
    arras_add_tapestry('line', __('Per Line', 'arras'), 'arras_tapestry_line');
}

Basically I have added:

| By <?php the_author_posts_link(); ?>

It looks good and works the way I want, but now I need to work in a Child Theme and thus theme upgradeable manner.

Do I write a function to replace

arras_tapestry_line

and if so do I include all the above changes? It doesn't seem to work. I get a nasty Parse Error.

Or do I hook

arras_add_tapestry

?

I appreciate your help!

Thanks,
Dave