Textpattern Tags

Most plugins provide functionality in the form of template tags, though they’re not limited to that. Plugin tags look and work exactly like the built-in Textpattern tags, and can be used in all the same places.

The Textpattern plugin template includes a file named zem_example_plugin.php. This includes several simple examples of Textpattern plugin tags, which we’ll examine below.

I’d recommend compiling and installing this plugin now. If you’re not already familiar with that process, it’s covered in part 2 of this series. With the zem_example plugin installed, you can use Textpattern’s plugin editor page to make some of the changes demonstrated below, and see the results for yourself.

Like regular Textpattern tags, a plugin tag can be self-closing:

<txp:zem_hello_world />

Or enclosing:

<txp:zem_lowercase>
HeLLo WoRLD
</txp:zem_lowercase>

The only sign that either of these tags are provided by a plugin is the zem_ prefix. That’s a naming convention as specified in the plugin template: all plugin tags should begin with a three-letter prefix unique to the author¹. In every other respect, these tags are exactly the same as any built-in <txp:... > template tag.

Both self-closing and enclosing plugin tags accept attributes:

<txp:zem_hello_world name="Bob" />
<txp:zem_lowercase foo="bar" baz="bing!">
HeLLo WoRLD
</txp:zem_lowercase>

These attributes can be accessed from within the PHP code; we’ll get to that later.

Enclosed content may be any mix of plain text, HTML, and other Textpattern tags, including other plugin tags:

<txp:zem_lowercase>
<txp:zem_hello_world name="BOB" />
Welcome back.
<txp:title />
</txp:zem_lowercase>

Tag handlers

Behind every Textpattern tag is a PHP function called a tag handler. Any time it encounters a tag of the form <txp:foo /> or <txp:foo>bar</txp:foo>, the Textpattern template parser will attempt to call a PHP function with the same name as the tag: foo() in this case. There’s no registration process or callback list; the PHP function definition is all that’s required to create the tag.

The tag handler for the self-closing zem_hello_world tag — from zem_example_plugin.php — looks like this:

function zem_hello_world($atts) {
   extract(lAtts(array(
      'name'  => 'Alice',
   ),$atts));

   // The returned value will replace the tag on the page
   return 'Hello, '.$name;
}

The $atts parameter will contain any attributes included in the tag. It’s explained in detail below.

An enclosing tag handler requires an extra parameter:

function zem_lowercase($atts, $thing='') {
   return strtolower(parse($thing));
}

The second parameter contains the tag’s enclosed content. It’s usually called $thing in Textpattern’s built-in tag handler functions, so we’ll stick with that name. Function parameter names aren’t significant in PHP, so you can use the name to $content in your own tag handler functions if you wish.

Attributes

The $atts parameter is required for all plugin tags, self-closing or otherwise. When the tag handler is called, $atts will contain an array of the attributes that were specified in the tag code, or an empty array if there were none. As an example, this tag:

<txp:zem_hello_world foo="abc" bar=5 />

..would produce the following $atts array:

array (
   'foo' => 'abc',
   'bar' => '5',
)

A tag with no attributes:

<txp:zem_hello_world />

..will produce an empty $atts array:

array (
)