Dev:Plugin Blocks

From Habari Project

Revision as of 03:37, 14 August 2011 by Konzertheld (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Blocks provide a way for plugins to produce content to be added to themes. Block output can be mapped to specific output locations in the theme by the user without having to write HTML or PHP.

Blocks should be designed so that the styling of the current theme can be applied to the content they produce, so that they look appropriate for their placement in the site (the context) and the page (the area).

A common use for blocks is to display sidebar content that can be reorganized.

See also Areas.


Block Plugins

To produce block content a plugin must register a template, and implement three hooks:

Add a template to the ones available in the theme.
Provides a list of blocks that are available to the system.
Produces a form that lets users configure the content of a block.
Produces the data content of a block based on the saved data about that block.


The action_init() method should be used to register the block template.

public function action_init()
	// other templates registered, and other initialization
	$this->add_template( 'block.myblock', dirname(__FILE__) . '/block.myblock.php' );


The filter_block_list() takes a paramenter of an associative array of the internal names and display names of blocks called $block_list. This array should be updated with internal and display name of your block and returned.

public function filter_block_list( $blocklist )
	$blocklist[ 'myblock' ] = _t( 'My Block' );
	return $blocklist;

The key of the array is passed to functions internally to identify the block prototype. When displaying the block to the user, the value of the array is used.


The action_block_form_myblock() method is used to create a configuration form for your block. Remember that it's possible to have multiple instances of a type of block, so this form configures one particular instance. The name of the action method includes the identifier key as returned by filter_block_list().

$form is the FormUI object instance that accepts the block data. $block is the Block object instance representing the block.

Habari automatically includes configuration options for the the block's title and whether that title should be displayed.

In the overwhelming majority of instances, the block plugins will handle their own forms and content. Calling every potential instance of a 'action_block_form' hook and returning null when the call is inapplicable to the block would be very inefficient. It might be useful to include a general-purpose action/filter for other cases, where a plugin would want to respond to some other plugin's block call, but that should not be the default for this function.

public function action_block_form_myblock( $form, $block )
	// $form is already assigned to a FormUI instance
	$form->append( 'text', 'some_value', $block, _t( 'Some Value:', 'myblock' ) );
	// No need to append a submit button as there is always a default form
	// No need to return values from an action hook

The action hook handles the form processing completely. The FormUI class can be augmented to store values, but it's usually easier to pass a storage string or an object that implements FormStorage.

The core Block class implements the FormStorage interface, allowing the values from the form to be stored directly into the block instance's row in the blocks table.


The action_block_content_myblock() method is used to provide the block's content, as configured for the particular instance. Again, the name of the filter method includes the identifier key as returned by filter_block_list().

$block is the Block object instance representing the block.

Block content is added by putting data into the $block properties, which is subsequently rendered separately from this hook by a template that is either block-specific or for generic block display.

public function action_block_content_myblock( $block )
	$block->image = Options::get( 'myblock_image' );
	$block->time = new HabariDateTime();

Block Templates

Blocks are rendered by passing their data values to a template, rather than by producing explicit theme-level markup from within the content generation routines.

The fallback for blocks is as follows:

  • {context}.{area}.block.{blocktype}.{blockname}.php
  • {context}.{area}.block.{blocktype}.php
  • {context}.{area}.block.php
  • {context}.block.{blocktype}.{blockname}.php
  • {context}.block.{blocktype}.php
  • {context}.block.php
  • {context}.content.php
  • {area}.block.{blocktype}.{blockname}.php
  • {area}.block.{blocktype}.php
  • {area}.block.php
  • block.{blocktype}.{blockname}.php
  • block.{blocktype}.php
  • block.php
  • content.php
  • {context}.php
The rewrite rule used to determine the page output
The name of the area in the template to output into
The internal name of the block type
The slugified block instance name

Plugins may include block.{blockname}.php templates for registration in their installation, which will allow a default rendering in a theme that has no specific template for the type of output that the plugin produces.

Blocks implement IsContent, and so they are rendered using the $theme->content($block) method. This passes the value of $block to the template as $content. Any properties that were set on $block will be available in the template on $content.

For example, using the data supplied from the action_block_content_myblock() example above:

* This is the block.myblock.php template
* $content is the Block object 
<img src="<?php echo $content->image; ?>"> <?php echo $content->time->format('h:ia'); ?>

Block Wrapper

It is also possible to supply a template to wrap any block that is output with some wrapping HTML. This may be useful for themes that wish to provide a uniform look to blocks without having to repeat the markup used to do so within each individual block template, allowing the block templates to render only the content of the block and not layout elements.

The fallback for the block wrapper template is as follows:

  • {context}.{area}.blockwrapper
  • {context}.blockwrapper
  • {area}.blockwrapper
  • blockwrapper
  • content

Here is a sample block wrapper template:

<div class="block<?php if($block->_first): ?> first<?php endif; if($block->_last):?> last<?php endif; echo ' index_' . $block->_area_index; ?>">
<?php echo $content; ?>

This template makes use of some special block rendering capabilities. The variables $block and $content are avaialable to the template. $content is the rendered output of the block, as produced by the block template for that block. $block is the Block instance, and has the following additional properties when rendered from the block wrapper:

If the block is the first within the area, this is true, otherwise false.
If the block is the last within the area, this is true, otherwise false.
This contains the integer index of the block within the area. The first block will be 1, the second block 2, etc.
The contains the rendered output of this block, and is identical to the $content variable.
The area into which the block is being rendered.
The internal integer id under which this block is stored. This is unique per block instance and could be useful for creating unique HTML id's.
A combination of user-assigned and system-assigned CSS classes that apply to this block.

With the exception of _first and _last, these special properties are also available within the block template itself. Note that the _area_index value is the absolute index of the blocks assigned to that area, even if some blocks are not displayed due to having no content.

The above block wrapper template can be simplified by using the css_classes property, which contains all of the properties shown there, plus some additional useful class names and any user-assigned class names:

<div class="<?php echo $block->css_classes; ?>">
<?php echo $content; ?>
Other Development Pages · Developer Introduction
Personal tools