Arras WordPress Theme

Take a look at this topic.

The poster wanted to add an advertising space to his sidebar and wrote it directly into sidebar.php. It works.

But.

You don't want to do that. It means when Arras Theme will be updated you have to redo it.

Is there any other way?

Yes.

Open sidebar.php and you'll see some code.

</div><!-- #container -->

<?php wp_reset_query() ?>

<div id="primary" class="aside main-aside sidebar">
<?php arras_above_sidebar() ?>  
    <ul class="xoxo">
        <?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar('Primary Sidebar') ) : ?>
            <li class="widgetcontainer clearfix">
etc. etc.

Notice the <?php arras_above_sidebar() ?> ?

That's a hook.

If you open actions.php you'll see this (somewhere in the file)

/**
 * Called before the main sidebar
 * @since 1.2.1 
 */
function arras_above_sidebar() {
    do_action('arras_above_sidebar');
}

In itself it doesn't do anything.

But I'll tell you now: it's immensly powerful. You can add a function to that hook. To any hook (Arras has several) actually.

This might sound like abracadra for some, but I'll give you an example of how to write a function which will attach the advertising space to that hook in sidebar.php without having to edit files in Arras Theme itself. But I'll start with simply adding a piece of text.

First of all: create a functions.php in your child theme, just an empty file.

For this Quick Guide I'm putting this in:

<?php

// We're going to add a few functions here

?>

Now I'm going to write a function named say_hi().

function say_hi() {
     echo 'hi';
}
add_action('arras_above_sidebar','say_hi');

Very simple and basic.

The result:

Now I'm going to expand it a bit, I only want to show it on the frontpage. Therefore I need to use a so-called Conditional Tag. In this is_home() will do. I will put it next to say_hi() and name it say_hi_again().

function say_hi_again() {
if (is_home()) {
    echo 'hi';
    }
}
add_action('arras_above_sidebar','say_hi_again');

The result on front page:

On every other page/post it only says hi:

It looks like crap though, let's add a div class to it.

function say_hi_again() {
if (is_home()) { ?>
     <div class="greet">
     hi
    </div>
    <?php }
}
add_action('arras_above_sidebar','say_hi_again');

Notice the differences? The 'echo' is gone and I had to break out of PHP and open it up again before the end of the function. I'm not going to elaborate on that too much, there's plenty of material on teh big Interwebz on that already.

Let's look at the result.

They are now positioned beneath each other because of the div class I added.
Time for some css. I want black letters, red background, bold letters and a bigger font.

.greet { color: #000; background: #ff0000; font-size: 16px; font-weight: bold }

(add this to the style.css of the child theme!)

Result:

I only did that last part to show a little trick later on.

Now it's time to try to add the advertisement. I'll keep the say_hi_again() and functions.php looks like this now:

<?php

// We're going to add a few functions here

function say_hi_again() {
    if (is_home()) { ?>
    <div class="greet">
    hi
    </div>
    <?php }
}
add_action('arras_above_sidebar','say_hi_again');

?>

Let's try some things

function put_ad_in_sidebar() {  
    echo '<img src="http://i45.tinypic.com/9hlvma.jpg"; />'; 
}
add_action('arras_above_sidebar', 'put_ad_in_sidebar');

Result:
And now I'll show you why I kept say_hi_again(). I'm going to add a priority to the actions. The only thing I need to change is the last part of the functions.
add_action('arras_above_sidebar','put_ad_in_sidebar', 1);
add_action('arras_above_sidebar','say_hi_again', 2);

Functions.php looks like this now.

<?php

// We're going to add a few functions here

function say_hi_again() {
if (is_home()) { ?>
    <div class="greet">
     hi
    </div>
    <?php }
}
add_action('arras_above_sidebar','say_hi_again', 2);

function put_ad_in_sidebar() {  
     echo '<img src="http://i45.tinypic.com/9hlvma.jpg"; />'; 
}
add_action('arras_above_sidebar', 'put_ad_in_sidebar', 1);

?>

The result:
They switched places. I added two actions to the same hook and established in which order I want them.

Breaking down the add_action stuff:
add_action('place_where_it_should_go', 'function_I_just_wrote', priority)

There's a fourth parameter ($accepted_args) but I'll skip that one for now.

This little guide gave you the basics on how to add actions. You can do a lot more with it. Arras Theme has several hooks (see actions.php) for you to play with. Next up will be a basic instruction on how to add filters, another great example of what you can do with Child Themes.

Quick Quide for Templates

WordPress checks for a couple of templates to see how something has to be displayed. Here a great image how WordPress handles it. Arras Theme has a couple of them, single.php, archive.php, etc. etc.

With Child Themes you can make your own which get prioritized above the ones Arras Theme uses. In this quick guide I'll make a (slightly) different version of single.php. I start out with copying single.php from Arras Theme and placing it in the Child Theme (Kuro) directory.

I'll keep it simple and add a text beneath the header and the content. This is single.php now.

<?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 arras_below_post() ?>
    <a name="comments"></a>
    <?php comments_template('', true); ?>
    <?php arras_below_comments() ?>
    
<?php endwhile; else: ?>

<?php arras_post_notfound() ?>

<?php endif; ?>

<?php arras_below_content() ?>
</div><!-- #content -->

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

Lot of stuff again and people who read the part about actions and filters might recognize some things, for example <?php arras_below_content() ?> is a hook.

Now I'll simply add the text 'In the part about filters I killed my postheader'.

<?php arras_postheader() ?>
        
      <div class="my-text"> In the part about filters I killed my postheader</div>
        
        <div class="entry-content">

I've placed it between the existing stuff and added a div for some custom styling.

Add some styling

.my-text { font-size: 14px; font-weight: bold; color: #800517; }

Result:

Not very exciting stuff but you can add php-functions too. I'll add a category-list after the author stuff. That's <?php wp_list_categories() ?>

    </div>
    
    <?php wp_list_categories() ?>
    
    <?php arras_below_post() ?>

Result:

You can do these little things for basically all templates and when Arras Theme gets updated the changes will still be there.

An advanced example of using filters

I've added Custom Taxonomies to my blog and now I want them to add to the postheader in single posts, I want them to show up under the category. I also want them to show up when they are actually there.

There are a couple of ways to do this, I can make a template and add it to the template or I can use the filter Arras Theme used to place the postheader where it is. In an earlier example I showed how to replace a filter. For this particular example I need what is already there, I only have to add a thing.

Luckily the filters stuff have the tools to do that. Arras Theme uses apply_filters('arras_postheader', $postheader). The last part of that is an accepted argument which I'm going to re-use while actually replacing the filter.

function my_head($postheader) {
echo $postheader;
$var = get_the_term_list( $post->ID, 'studio',' ', ', ', '' );
if (!is_page() && !empty($var)) {
echo '<strong>Studio:</strong>' . $var . ' ';
}
$vartoo = get_the_term_list( $post->ID, 'jaar',' ', ', ', '' );
if (!is_page() && !empty($vartoo)) {
echo '<strong>Jaar:</strong>' . $vartoo;
}
}
add_filter('arras_postheader', 'my_head');

See what I did? I used $postheader as an argument for my own function and echo'd it in the second line. After that I added my own stuff.

I could have written this function with breaking out of php a couple of times (see an earlier example) but I choose to use apostrophes in this example.

The result:

So, you can not only replace a filter completely, you can use it in your function and re-use it.

Okay, so you do know there's an action hook and yet you choose to edit the template? Why?

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

function add_my_sidebar() { ?>
<?php if (is_archive()) { ?>
<div class="my-sidebar">
<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar('Test') ) : ?>
<?php endif; ?>
</div>
<?php }
}

add_action('arras_above_content', 'add_my_sidebar');

Same result.

Sure. But I'm not sure what you want actually. You want a single.php to handle a single post with an archive at the bottom? Am I correct?