Presets

From Habari Project

Jump to: navigation, search

A Preset is a named, pre-configured set of parameters to Posts::get().

See Retrieving Posts for information on using Posts::get() to retrieve posts.

Contents

Purpose

Consider the home page of a simple site, which displays only the last five published entry type posts. The parameters for retrieving those posts would look like this:

$posts = Posts::get(array(
  'status' => 'published',
  'content_type' => 'entry',
  'limit' => 5,
));

If this call is present in a theme class to display the posts on the home page, it will work effectively. But then consider a plugin that adds a "tweet" content type, which is meant to be displayed in the main post output with a different style. If the parameters passed to Posts::get() are coded as an array, as above, then the plugin will not be able to easily adjust the parameter that controls the content types that are selected for display on the home page.

To avoid this, we introduce the concept of a Preset.

Implementation

Implementing a preset consists of constructing multiple interdependent parts.

Creating a Preset

To create a preset, we must implement a filter hook function. The Preset called "home", which defines the parameters which will be used for the call to Posts::get() on the home page, is already defined in core Habari in the Posts class:

	/**
	 * Provide some default presets
	 * @static
	 * @param array $presets List of presets that other classes might provide
	 * @return array List of presets this class provides
	 */
	public static function filter_posts_get_all_presets($presets)
	{
		$presets['page_list'] = array( 'content_type' => 'page', 'status' => 'published', 'nolimit' => true );
		$presets['asides'] = array( 'vocabulary' => array( 'tags:term' => 'aside' ), 'limit' => 5 );
		$presets['home'] = array( 'content_type' => Post::type( 'entry' ), 'status' => Post::status( 'published' ), 'limit' => Options::get('pagination', 5) );
 
		return $presets;
	}

Here, the defaults are defined essentially the same as the initial array. This will allow the default behavior when using this preset to be the same as that array.

Adding a similar function to a plugin or theme class will allow it to supply new or override old presets.


Using a Preset to fetch posts

To use the preset, the theme need only pass the name of the preset to Posts::get() like this:

$posts = Posts::get('home');

This causes Habari to get the array of values that define the "home" preset and use them to fetch the matching posts.

Altering the properties of a Preset

To implement a plugin that alters the preset to add tweets, we need to create a filter in a plugin that alters the preset to include the additional content type:

	public function filter_posts_get_update_preset($preset_parameters, $presetname, $paramarray) {
		switch($presetname) {
			case 'home':
				$content_type = isset($preset_parameters['content_type']) ? 
					Utils::single_array($preset_parameters['content_type']) : 
					array();
				$content_type[] = 'tweet';
				$preset_parameters['content_type'] = $content_type;
				break;
		}
		return $preset_parameters;
	}

When Posts::get() receives the call to display the "home" preset, it calls this filter in the plugin, passing the array of the preset's parameters as the first parameter of the filter function. If the preset name (the second parameter) is the one that we want to alter, then we make the adjustments we need to the array before it is returned.

The third parameter in this filter contains any additional parameters that were supplied to Posts::get() when it was called.

Additional Parameters

It is possible to add additional parameters to the Posts::get() call beyond the Preset, but it requires a different calling convention, since presets are usually passed as a single string parameter directly in the call.

To pass additional parameters into Posts::get() along with a Preset, pass the Preset as a parameter also:

$posts = Posts::get(array(
  'preset' => 'home',
  'limit' => 15,
));

If some parameters are defined in both the Preset and in the call to Posts::get(), then the additional parameters in the call will override the parameters in the Preset.

Preset Fallbacks

It is possible to define multiple presets to try during a Posts::get() call. Each one is tested in order, and the first one that exists is used for display. This is useful if a plugin wants to provide a way to specify exactly what posts should be displayed in certain circumstances, but use a more generic Preset if that more specific Preset is not defined.

For example, a plugin may provide a Block that displays some posts. It may use the "asides" Preset to do this by default, with a fallback of "home". If the "aside" Preset isn't defined, then the "home" Preset is used instead.

To specify multiple Presets, add them as an array in a parameter to the Posts::get() call:

$posts = Posts::get(array(
  'preset' => array('asides', 'home',),
));
Personal tools