From Habari Project
Greetings WordPress Themer!
Indubitably you've arrived at this page looking for the "secret sauce" that makes Habari theming as easy as WordPress theming. This page is designed to present a brief explanation of the differences in methodology so that you can quickly get up and running.
Rather than executing functions within the template, Habari builds the required output prior to executing each template and stores it in PHP variables. The variables can then be output using the simplest construction of PHP:
<?php echo $title; /*output the value stored in the $title variable */ ?>
A default habari theme produces certain outputs for specific types of pages. By creating a custom theme.php file to distribute with your theme, you can add more variables that contain other values that you define.
What's nice about Habari is that rather than having a separate function for each property of a post, you can treat a post as a thing that has values associated to it.
Just like you might think of a post as a collection of values for title, body, and permalink, so does Habari. Consider a post stored in a variable named $post. You can't output $post directly (nor would you want to if you intended to style it) because it is a collection of values. In Habari-speak, this is a "Post Object".
The Post Object has "properties" that correspond to the values associated to that post. To access the title property of a Post Object, you use the syntax $post->title. This means, "of the object stored in $post, return the value for title". So to output the title of a post, you would just do this:
<?php echo $post->title; ?>
It's also clear from this construction that you are outputting the value of the title of the post, not the title of the page or the title of the blog, which could be different. You might contrast this with WordPress' the_title() template tag, which happens to output the title of a post, if you didn't realize it from reading the name of that PHP function.
When you realize that the value of a property can be virtually any value, you come to understand that a property of an object could even be another object. Look at this example:
<?php foreach( $post->comments as $comment ):?> <h4><?php echo $comment->name; ?></h4> <div class="commentbody"><?php echo $comment->body; ?></div> <?php endforeach; ?>
What does this do? The foreach command executes the code between the foreach and the endforeach for each value stored in $post->comments. $post->comments is an array (a variable that stores multiple things) of comments. During each pass of the the foreach loop, the variable $comment is assigned to a single new comment from $post->comments.
Inside the loop, the property values of $comment, a Habari Comment Object, are output. The end result is an output of all of the comments attached to that post.
In WordPress by default, the comments are built mysteriously in the innards of its core, and you don't have much control over which ones are displayed. Displaying comments for more than one post on a page could be pretty complicated. Not with Habari -- just build one foreach loop to go through all of the posts on the page, and put another inside it to go through each comment on each post.
WordPress uses a system of filters to allow plugins to alter the content when it is output. This is used to implement features like Textile or Markdown, which convert the content of the post from an easily-read text format into well-formed HTML. You might also use filters like this to replace post titles with stylized images, or replace special codes in your post with content from external sources. In WordPress, these filters are implemented transparently when you call the various template tag functions, and happen regardless of the location from which the function is called.
Habari also has this capability, but takes it a step further.
Themes in Habari have the ability to specify the context of a property's use. For example, if you're on a page that is designed to display multiple posts, you might want to display a summary of the post rather than the whole thing. At the same time, you still want the whole post to appear when showing the post by itself from its permalink page.
To accomplish this, you can apply filters to the properties when they're output. For example:
<?php echo $post->content_out; ?>
Adding "_out" to the property $post->content applies the "out" filter to the value of $post->content. Any plugin that implements a function to alter the post content on the "out" filter will affect this output. The suffix "_out" could be anything, including "_summary", which might have a filtering function applied to it to summarize the post content.
Because Habari themes inherit all of the properties of Habari's plugins, it's possible to implement this summarizing properties directly in the theme itself, allowing you to provide both a hook for context-driven filtering and the functionality that produces it.
Why does Habari do it this way?
Flexibility is what makes Habari better at theming than WordPress. In WordPress there is no template engine, thus you are bound to the proprietary function names, which usually require confusing parameters to get formatting correct. Habari has the ability not just to add your own template variables from a custom theme.php, but replace the theme engine used entirely with something else. You could use any template engine such as smarty, phptal, phammable, phaml, etc... Allowing you to learn something that you may find easier than using the default "raw php".
Habari provides the tools that makes the PHP language useful for templating, rather than trying to build another layer on top of an already robust language.