From Habari Project

Jump to: navigation, search

Habari embraces the Model-View-Controller pattern to separate code from presentation. That means that theme files are really supposed to simply output data to the user's browser, and shouldn't be doing a lot of logic processing or decision making. It's all too easy, using Habari's RawPHP theme engine, to forget this pattern and just slap all kinds of conditional PHP code into your theme. That's the wrong way to do it!

All RawPHP themes require a theme.php file that defines the class that will be used for that theme. The default Habari themes' theme.php files each provide a couple of useful examples of how you can use the file to control the output of your theme in various ways. The various Format::apply calls are made outside of your class declaration, and are used to setup things like whether to show post excerpts, how to display dates and times, and the like. The add_template_vars() method is used to make variables available to your theme files. But there's a whole lot more you can do!

You can -- and should -- declare methods inside your theme.php file to handle as much conditional logic as you can. This keeps your theme files nice and small, and allows you to more easily re-use code. Here's a simple example: when displaying a post's title, you want to also display the number of comments attached to it. In the Habari K2 home.php file, you'll find this:

<span class="commentslink"&gtl<a href="<?php echo $post->permalink; ?>#comments" 
     title="<?php _e('Comments to this post'); ?>"><?php echo $post->comments->approved->count; ?>
<?php echo _n( 'Comment', 'Comments', $post->comments->approved->count ); ?></a></span>

You'll find the exact same code in entry.single.php and entry.multiple.php. If you want to change the text that's displayed for this block, you need to change it in at least three files. This gets tedious pretty quickly. Instead, replace that entire block in all three files with this:

<?php $theme->comments_link( $post ); ?>

Then, in your theme.php file, add this:

public function theme_comments_link( $post )
     echo '>span class="commentslink"&ht;<a href="' . $post->permalink . '#comments"';
     echo ' title="' . _t('Comments to this post') . '">' . $post->comments->approved->count;
     echo _n( 'Comment', 'Comments', $post->comments->approved->count ) . '</a></span>';

Now you have a single function displaying the comment details for the post, allowing you to make changes in one location, while automatically updating the output in any template file that invokes that function.

Another great use of theme.php is to simplify embedding repeated elements, like advertisements, in your theme. You can use something like this:

public function theme_ad()
     $ad= '';
     if ( ! User::identify() ) {
          $ad= <<<END
<script type="text/javascript"><!--
google_ad_client = "xyz123";
google_ad_slot = "123987";
google_ad_width = 120;
google_ad_height = 240;
<script type="text/javascript"
     return $ad;

Then simply add $theme->ad() anywhere in your template files that you want to display that ad. You can create multiple functions for multiple ads as necessary. You'll note that logged-in users don't see the ads, so remember to log out if you want to check your ad placement after making changes (or remove that bit during testing, and put it back in when you're all done).

You can add as much additional logic into these theme methods as you need. Using the previous theme_ad() method, you could add additional logic to only display ads to people based on their HTTP referrers, or whether or not they've commented on your site before based on cookie, or simply the time of day.

Use your theme.php file to consolidate as much conditional logic as you can. This keeps your individual template files clean and easy to ready, and helps you reduce bloat by re-using code. You can make changes in one file and enjoy the results of those changes across multiple template files, reducing errors and greatly simplifying theme maintenance. Be sure to read Customizing Theme Behavior for more details!

Personal tools