From Habari Project

Jump to: navigation, search

Shortcodes are an easy way for plugins to allow you to embed dynamic output in your post content. When used in the title or content of a post, Habari will replace the shortcode used with the corresponding dynamic data provided by a plugin.



Shortcodes come in two styles. In one style, the shortcode is self-contained. In the other style, the shortcode can wrap other content.

Here is an example of a self-contained shortcode that embeds the current date in the post content:

   The current date is [currentdate/].

The output of the post content with this shortcode would look like this:

   The current date is July 4th, 2012.

Here is an example of a shortcode used to wrap content:

   And in this scene, he reveals the truth to Luke: [spoiler]Darth Vader is Luke's father![/spoiler]

The output of the post content with this shortcode would look like this, which would presumably have some CSS and javascript to allow the text to be revealed to curious readers:

   And in this scene, he reveals the truth to Luke: <div class="rot13">Qnegu Inqre vf Yhxr'f sngure!</div>

Nesting Shortcodes

It is also possible to nest shortcodes to produce output:

   Want to know when my birthday is? [spoiler]My birthday is [currentdate/].[/spoiler]

This would be output as:

   Want to know when my birthday is? <div class="rot13">Zl oveguqnl vf Whyl 4gu, 2012.</div>

Shortcode Parameters

Shortcodes can accept parameters, which are passed on to the plugin that handles producing their output.

   Please fill out the following form:
   [form name="contact"/]
   Be sure to fill out all fields completely!

The shortcode above sends the value "contact" for the field "name". This could be used by the plugin that produces the "form" shortcode output to select the correct form for display. Additional parameters could be passed to adjust the output more.

Implementing Shortcodes

Shortcodes can be implemented in code in themes or plugins by adding a filter function. The filter function is named filter_shortcode_{code} where {code} is the name of the shortcode.

To implement the filter for the shortcode [currentdate/] above, use code like the following:

	function filter_shortcode_currentdate($content, $code, $attrs, $context)
		return HabariDateTime::date_create()->format(isset($attrs['format']) ? $attrs['format'] : 'M j, Y');

The arguments to the filter function include:

The content of the shortcode, including the shortcode tags, that will be replaced.
The text of the shortcode, in this case, "currentdate". This is useful if more than one shortcode is handled by the same function.
An array of attributes included in the shortcode.
The content of the shortcode, not including the shortcode tags.

Applying Shortcodes to Other Fields

By default, shortcodes are only replaced in the title and content fields of a post. If you add additional fields to a post using the filter_post_get hook, you can include those fields in what fields shortcodes apply to.

First, you need code that creates a new field for a post:

	function filter_post_get_6($out, $name, $post)
		if($name == 'myfield') {
			if(isset($post->info->myfield)) {
				$out = $post->info->myfield;
		return $out;

The above code adds a virtual field to post objects that allows access to $post->info->myfield via $post->myfield.

Then you need to add the field "myfield" to the list of fields that will be filtered for shortcodes:

	function filter_shortcode_fields($fields, $post)
		$fields[] = 'myfield';
		return $fields;

This allows the value supplied by $post->myfield to have shortcodes within it properly handled.

Personal tools