Creating a Custom Theme
From Habari Project
Habari supports a powerful and flexible way to create custom themes, and this article describes in detail how to create one. A good way to get started is to use the default K2 theme or one of the other available themes as a reference. Create a new directory in /user/themes/ for your new theme, and put all of your theme files in this directory. The minimum requirement for a theme is an XML file that describes the theme, and some template files, with a minimum of the home.php template. Themes may also optionally—and almost always will—include a file called theme.php, which is used to customise theme behaviour. Themes may also include a screen shot to be shown on the Admin | Themes page. The screen shot should be in png, jpg, or gif format, and be 150px high by 200px wide for optimal display (or some 3:4 ratio, as the image will be resized to those dimensions). The screen shot should be named screenshot.file_type, i.e., screenshot.png.
Contents |
theme.xml
The first step in creating a custom theme is to define it's basic properties in theme.xml within the theme's base directory. These properties will be used to identify the theme to users, give you credit, and appropriately version the theme through its life.
| Description | |
|---|---|
| <name></name> | The name of the theme. |
| <author></author> | Author's name or whomever is being credited with the design. |
| <url></url> | Location at which the theme can be found. |
| <version></version> | Current version of the template |
| <description></description> | A description of the template |
| <template_engine></template_engine> | The template engine that the theme uses. |
Example theme.xml
<?xml version="1.0" encoding="UTF-8" ?> <theme> <name>K2</name> <author>K2 Team</author> <url>http://getk2.com/</url> <version>1.0</version> <description>A port of the popular design K2 and first Habari "theme"</description> <template_engine>rawphpengine</template_engine> </theme>
You can now visit your Admin -> Themes page and activate your new theme, however, if you visit your site you will be presented with a blank page. This is because as yet there are no templates, so Habari does not know how to display anything.
theme.php
This optional file can be part of your theme. By including it, you can provide additional functionality to your theme. If you do not include it, the core theme functions will be used.
The theme.php file should contain a class that extends Habari's own Theme class. This class can be used to override Habari's default behaviour and to define functions that your theme can call. For example, you might define a function to format tags in a particular way. See Customizing Theme Behavior for more information.
The instance of your custom theme class — or the default theme if you have not defined your own — is available in your theme as the $theme variable. Thus, functions you define in your theme class can be called as $theme->my_function().
A custom theme class has all of the same abilities as a plugin. If you add functions in the theme class that use the plugin prefixes (filter_, action_, etc.), Habari will treat them as though they were in an active plugin. Only the current theme's theme class will have functions like this enabled.
Template Files
Habari has flexible template support, allowing you to customise any aspect of a how a blog is displayed. The way that the templates are processed is dependent on the template engine being used. Currently Habari supports rawphpengine, however, it is designed so that any number of other engines can be supported (Smarty and PHPTal engines are some examples of template engines that have been discussed for inclusion with Habari). More information can be found at Template Engines.
Templates using the rawphpengine are simply HTML files with embedded PHP. While you can use any code you like in your templates, you should try to keep the templates as simple as possible. Ideally, complex code should be located in theme.php and the output included in variables, which you simply echo in your template.
Most themes will include a number of different templates, each being called in different circumstances. This section will describe some of the most common template files. Note that this is far from an exhaustive list of templates recognized by Habari. In fact, Habari will use templates as specific as for a particular post id or date. See Template File Hierarchy for information on how Habari decides what template to use when displaying particular content.
home.php
This template is used to display the front page of the blog. Usually, this template will display the most recent blog entries.
single.php
This template is used to display a single post, no matter what it's content type. A theme developer may choose not to use this template but instead have specific templates for a content type, such as entry.single.php.
multiple.php
Similar to single.php, this template is used when multiple posts are to be displayed, no matter what the content type. This means that this template might be displaying entries and pages on the same page. Again, a theme developer may choose not to include this template but to use specific templates, such as entry.multiple.php.
tag.php
The tag.php template is used for displaying queries for a specific tag. By default, using the $post->tags_out variable, tags are linked to display such a query.
search.php
The search.php template is used when displaying the results of a search. As with multiple.php, posts may be any content type, so this template will display a mixture of entries and pages on the same page.
404.php
The 404.php template is used as a fall back when attempting to serve a post or page that the site can not find. The template can contain any type of information, including calling a search form, a list of tags, or simply a message notifying the visitor that they've reached a bad URL.
login.php
The login.php template is an option for themers to add if they want to customize the login screen for registered users to match the active theme. Depending on the theme design, this template can either call an internal template loginform.php or contain the code directly, depending if the designer wants the login in multiple locations. If no login.php template is provided, Habari uses a default login screen.
Internal Templates
Themes can also include internal templates for common code that are never called directly by Habari. For example, if your theme has a sidebar that should be displayed on every page, you could have a template called sidebar.php. You can simply call include sidebar.php in the appropriate place in each template to display the sidebar, however, the ideal way to include these ancillary templates would be to use $theme->display ('sidebar'); or what ever template it is you are looking to include. This allows for plugins to do things with the template that a regular include would not. Other examples templates that your theme might include are templates for the header and footer. Other common internal templates would be searchform.php, commentform.php and the aforementioned loginform.php.
Plugin Output
It's likely that you'll want your theme to display output from plugins, if those plugins are active. Habari provides a number of ways of doing this. If the plugin outputs content directly, you can check if the plugin is loaded and use that data in your template. Checking that a particular plugin is loaded is simple, and is illustrated here by checking if the pingback plugin is active. (A more complete example demonstrating the active condtion). The is_loaded() function can also take a second parameter that specifies a particular version of the plugin.
<?php Plugins::is_loaded('pingback'); ?>
Alternatively, and a better way of doing this is to use theme functions. These are special functions that let theme developers safely insert content returned by plugins, meaning, if the function is in a theme template, and the plugin is not active, nothing will out put and the theme will ignore the function. More detail can be found under Theme Functions.
Variables Available to Custom Themes
In addition to the $theme variable that holds a reference to the theme, other variables available to theme developers are described in the table below.
| Variable | Description |
|---|---|
| $template | The name of the template Habari has chosen for display. |
| $template_file | The full path to the template Habari is using for display. |
| $matched_rule | An object representing the rewrite rule that was matched to transform the requested URL. |
| $request | An object representing the original request. |
| $posts | An object that holds the posts that are available for display. Individual post objects can be accessed through this variable. |
| $page | The current number being displayed. For example, if multiple posts have been returned in response to a request, these may be spread across several pages. |
Content-Types
There are two methods of outputting posts within themes. The first method is to directly call the $post or $posts object. However, this does not allow plugins to provide new content-types. The alternate method simply involves calling the $theme->content($post, $context) method, which will output the appropriate template.
<?php foreach($posts as $post): ?> <?php $theme->content($post, 'multiple'); ?> <?php endforeach; ?>
This will select the most accurate template (which can be provided by the theme or a plugin) and output it. At the very least, you should include a post.php template. The hierarchy of selecting the appropriate template is as follows:
- {context}.{type}
- {context}
- {type}
- post
