Theme Functions

From Habari Project

Theme functions are special functions in Habari themes that allow a theme to safely insert custom content from plugins.

Contents 1 How to use Theme Functions 1.1 Parameter Passing 1.2 Standard Calls 2 Implement a Theme Function in a Plugin 3 How to Reorder Theme Function Results

How to use Theme Functions

Using a theme function in a Habari theme is very simple. Consider the following use.

Imagine that you have created a theme and you want to allow plugin developers to insert content of their own into your sidebar area. Insert the following code into the sidebar where you want the plugins to output their content in your theme:

<?php echo $theme->sidebar(); ?>

This will allow any plugin that implements the theme_sidebar() function to insert output at that location.

A typical place where you will find this is in the header and footer areas of the core themes. In these locations you will find calls to $theme->header() and $theme->footer(), respectively. These calls allow plugins to add output to those areas that enable special features, like those that require javascript functions or additional CSS includes.

Parameter Passing

It is also possible to pass parameters to theme functions. For example, you may wish to use a plugin function to display a human-readable version of the number of comments on a post.

To do this, you would simply pass the Post object and the formatting strings to the theme function:

<?php echo $theme->comment_count( $post, 'No comments', '1 Comment', '%d Comments' ); ?>

The plugin that supplies the output will detect the number of comments on the post, and select the correct formatting string to use based on that number. The plugin should also provide the parameters it expects in the call.

Standard Calls

To make plugins more compatible, a list of standard functions should be available for reference.

• header() - Returns output for the header area
• footer() - Returns output for the footer area
• sidebar() - Returns output for the sidebar area

Themes can call any function without fear of it being implemented. An unimplemented theme function will simply output nothing without generating an error.

Themes can execute special functions that are theme-specific so that they or specialized plugins can implement their specific needs.

Implement a Theme Function in a Plugin

To implement a theme function in a plugin, you must create a function using the "theme_" prefix that returns the value that you wish to output.

For example, if you want to output a line of javascript into the theme header, you must return a value for the "header" theme hook. You would do this by creating a function in your plugin class named "theme_header" that returns this value:

function theme_header( $theme )
 {
   return <<< MYSCRIPT
   <script type="text/javascript">
   var foo = 6;
   </script>
 MYSCRIPT;
 }

The value that you return is output when the theme calls $theme->header().

theme_* functions always have the Theme object passed as their first parameter. All additional parameters passed from the theme are added after the Theme parameter. For example, to implement the theme function comment_count() above:

function theme_comment_count( $theme, $post, $zero, $one, $more )
 { ... }

Note that unlike plugin filter implementations, the initial return value is not passed in as an argument. If a theme function implementation should not output a value, it may return emptystring.

How to Reorder Theme Function Results

All theme function return values are accumulated in an associative array as they are processed, and then imploded before returned for output. The index of the array is the module name (class name) of the function called or the function name itself if the function is not in a class.

Before the values of the array are imploded, they are passed to the plugin filter with the prefix "theme_call_" for the requested theme function.

For example, if the theme calls $theme->header(), the process is as follows:

1. The theme calls $theme->header().
2. The theme_header() function in every active plugin is invoked.
3. The results of each function are stored in an associative array, indexed by module name.
4. The filter_theme_call_header() function in every active plugin is invoked with the same parameters as used for theme_header(), but using the array of returned values as the return argument.
5. The array of values filtered by filter_theme_call_header() is imploded.
6. The imploded value is returned as the result of the $theme->header() call.

During the call to filter_theme_call_header() any plugin that implements that function could manipulate the individual values in the array, add new values to the array, delete elements from the array, or rearrange the order of the array elements.

Using these functions in tandem, Habari could, for example, provide a way to output arbitrary data to the sidebar (by implementing theme_sidebar()) and also allow the user to specify the order in which that output would appear (by implementing filter_theme_call_sidebar()).