Dev:Theme Functions

From Habari Project

Jump to: navigation, search

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


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. Please note that this is a bad example because you could better do it with blocks.

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.

Theme Function Suffixes

Theme functions may be called plainly within the theme as shown above. The output from the theme or any plugins that respond to that theme function are concatenated and output to the location where the the theme calls the function. This is the default behavior when calling theme functions.

Theme functions also provide ways to access the values that are produced for output without rendering the values to the page. These are accessed using special suffixes to the theme functions.

_return added as a suffix to a theme function will return the individual results as an array. $theme->header_return() would return the values that would be rendered to the theme. Each individual plugin or theme response is returned as an element of the returned array.

_end added as a suffix to a theme function will return and echo only the last element of the array that would be returned from the _return suffix. $theme->header_end() would output and return the last thing added to the header output.

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;

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()).

Special Theme Functions

Special theme functions are defined in the core Theme class itself that implement core Habari features. These are listed below.

Renders the provided parameter value using a template based on its type.
Outputs blocks of content that have been created and assigned to that area.

Theme Function Scope Restrictions

Unlike other plugin hooks, Habari limits the scope in which theme functions will execute.

A theme function will only execute on the class of which the active theme instance is being addressed. If your theme class extends another theme class, only the theme functions within your theme class will be called when an instance of your theme is the active theme.

This prevents theme hooks from being called multiple times, once for existing in the base class and once for existing in the extended class, even though the extended class may not explicitly define the theme function.

If you want to hook a theme function from a theme class you extend, you must explicitly declare the function and call the parent function (or perform some similar action).

In most cases, you need not worry about this, since this feature exists specifically to prevent unexpected behavior. It does not affect any other plugin hooks, and would very rarely affect even themes in a way that would be considered adverse.

Other Development Pages · Developer Introduction
Personal tools