Two Kinds of Tags¶

There are two kinds of tags: Single tags and tag pairs. A single tag does not have a closing tag:

{exp:randomizer:set_one}

Single tags are designed to return a single value. Tag pairs look like this:

{exp:xml_encode}
    Stuff between the tags
{/exp:xml_encode}

Tag pairs allow you to process the information contained between the tags. In the above example, the text between the pairs would be encoded with XML entities.

Returning a Value¶

Your new class is useless unless it can return a value. There are two ways to return a value depending on whether your tag has three segments or two.

Two Segments¶

The above tag only provides the plugin class, and no method, so it will use a constructor. Since constructors in PHP do not have return values, we will assign it to a public class property called: $return_data:

class Hello_world
{
    public $return_data = '';

    public function __construct()
    {
        $this->return_data = 'Hello World';
    }
}

Three Segments¶

With tags that use three segments you can return directly since a class method is being called. Consider a tag with this syntax:

{exp:hello_world:bold}

The third segment represents a method called bold(), which can return a value directly:

class Hello_world
{
    public function bold()
    {
        return '<b>Hello World</b>';
    }
}

You could create a class with several methods this way:

class Hello_world
{
    public function normal()
    {
        return 'Hello World';
    }

    public function bold()
    {
        return '<b>Hello World</b>';
    }

    public function italic()
    {
        return '<i>Hello World</i>';
    }
}

Each function would be accessible using these tags:

{exp:hello_world:normal}
{exp:hello_world:bold}
{exp:hello_world:italic}

Processing Content Within Tag Pairs¶

Often you will want to process content contained between a pair of tags. Let’s create a simple tag that makes text bold to illustrate how this is done. Our example plugin will have this syntax:

{exp:bold}
    Some text we want to process.
{/exp:bold}

You will be able to use this plugin anywhere in a Template. You can even put this tag within another tag in order to affect a variable:

{exp:channel:entries}
    {exp:bold}{title}{/exp:bold}
{/exp:channel:entries}

In following our naming rules, we will create a plugin file named: pi.bold.php. And we will create a class with this syntax:

class Bold
{
    public $return_data = '';

    public function __construct()
    {

    }
}

So how do we fetch the content contained within the tag pairs? Using the following variable:

ee()->TMPL->tagdata;

Here is how the variable is used:

class Bold
{
    public $return_data = '';

    public function __construct()
    {
        $this->return_data = ee()->TMPL->tagdata;
    }
}

Of course you’ll want to do something with the data before you return it, so let’s make it bold:

class Bold
{
    public $return_data = '';

    public function __construct()
    {
        $this->return_data = '<b>'.ee()->TMPL->tagdata.'</b>';
    }
}

Parameters¶

Since tags will often have parameters, the template engine makes it easy to fetch them using the following variable:

ee()->TMPL->fetch_param('param_name');

To see how this is used, let’s create a plugin that lets you format text based on the parameter. Our new plugin will have this syntax:

{exp:format type="uppercase"}
    Some text to process.
{/exp:format}

We will allow the following parameter choices:

• type="uppercase"
• type="lowercase"
• type="bold"
• type="italic"

Create a plugin file named pi.format.php and in it put this:

class Format
{
    public $return_data = '';

    public function __construct()
    {
        $parameter = ee()->TMPL->fetch_param('type');
        $this->return_data = ee()->TMPL->tagdata;

        switch ($parameter)
        {
            case "uppercase":
                $this->return_data = strtoupper(ee()->TMPL->tagdata);
                break;
            case "lowercase":
                $this->return_data = strtolower(ee()->TMPL->tagdata);
                break;
            case "bold" :
                $this->return_data = "<b>".ee()->TMPL->tagdata."</b>";
                break;
            case "italic":
                $this->return_data = "<i>".ee()->TMPL->tagdata."</i>";
                break;
        }
    }
}

Passing Data Directly¶

ExpressionEngine allows any plugin to be assigned as a text formatting choice in the Publish page of the Control Panel. In order to allow a plugin to be used this way it needs to be able to accept data directly. This is how it’s done.

Add a parameter to the function. It’s best to make the parameter conditional so it will know whether it’s being used in a template or directly as a formatting choice:

class Bold
{
    public $return_data = '';

    function __construct($str = NULL)
    {
        if (empty($str))
        {
            $str = ee()->TMPL->tagdata;
        }

        $this->return_data = "<b>".$str."</b>";
    }
}

The above tag can then be assigned in the Publish page, allowing you to run your channel entries through it.