Plugins

Create tags for templates.

A plugin lets you create tags to display output into templates. For example, {{ entries:listing }} is a plugin — a first-party one, but a plugin nonetheless. A plugin tag is made up of two parts:

• the name of the add-on where the plugin can be found
• the method within the plugin object to call

The {{ entries:listing }} tag will display the result of the listing method in the entries plugin object.

Creating a Basic Plugin

The first step in creating a plugin is creating the file containing the object that will hold all of your tag’s methods. The file itself will be named after your add-on, for example, if your add-on is in a folder called flannelize, your plugin file will be pi.flannelize.php. The pi is for plugin. This file goes on the root-level of your add-on’s folder.

Next, within that file we need to create an object that extends Statamic’s Plugin object. The name of the object must be Plugin_ followed by the name of your add-on, like so:

class Plugin_flannelize extends Plugin
{

}

Finally, we need to create callable tags. This object by itself won’t do anything, as there are no methods within it to call. Let’s create a plaid method, which will become a callable tag by using {{ flannelize:plaid }}.

class Plugin_flannelize extends Plugin
{
   public function plaid()
   {
      return "PLAID!"
   }
}

There, you’ve just made your first plugin. This is the most basic of examples, and is relatively useless, but serves to illustrate how simple creating new tags can be. We’re just returning a string here, but remember that this is just PHP, and you can do anything that PHP can do.

Getting Input

Plugins, like all add-on aspects, have access to the add-ons configuration file (if one exists). You can look up values from your configuration file with the $this->fetchConfig method. Configuration files are a great place to store default values, especially for values that a user may want to change site-wide.

However, plugins also have a second way to gather input from users: through parameters passed on the tag itself. When you use {{ entries:listing }} for example, you’ll usually supply a folder to tell the tag which folder you want to look in. Your plugin can access these values with the $this->fetchParam method.

For example, if your user creates a tag that looks like this:

{{ flannelize:plaid exclaim="Yeeehaw!" }}

You can retrieve that value in your plugin’s method like so:

class Plugin_flannelize extends Plugin
{
   public function plaid()
   {
      return $this->fetchParam("exclaim");
   }
}

In some cases, you may want to provide a default value in your add-on’s configuration while letting users optionally override that value as a parameter. Rather than checking for one and then the other, we’ve set up $this->fetch as a helper for you.

This method will look in the user-set parameters and will return that value if its found, otherwise, it will look in your configuration and return that value if its found. If none are found, it will return null.

Single Tags vs. Tag Pairs

To create a single tag, something that stands alone by itself and doesn’t require a closing tag, your tag method must return a string. Within a template, your tag will be replaced with that returned string.

Creating a tag-pair is equally as straight-forward; rather than returning a string, your tag must return an associative array, where the name of each key will become a tag usable within your tag-pair. For example, if your method returns an array that looks like this:

Array(
   "tree" => "maple",
   "path" => "dirt",
   "sky" => "blue"
);

The {{ tree }}, {{ path }}, and {{ sky }} tags will be available within your tag-pair — they will be replaced by the values you return, so tree will become maple, etc.

An Advanced Technique for Tag Pairs

Returning an array from a tag-pair method will cause Statamic to automatically process the content between the tags, replacing values as needed. However, a tag-pair doesn’t need to return an array.

The value of what a user has entered within your tag-pair is stored in $this->content in your Plugin object. If you need to do something like loop through the content a couple of times (as entries:listing does), you can use $this->content with Parse::template to manually parse your tag-pair’s content. Using Parse::template will return a string, which you can then return from your tag-pair.

This probably won’t be necessary most of the time, but it’s worth knowing that it is possible if you need to do it. Just remember, returning a string from a tag-pair means no automatic content-parsing from Statamic.

Everything Works Together

Finally, remember that your plugin object shares the same namespace as any other aspect of your add-on, and can get and set data just like the rest of them. You may not always need to store or retrieve data to make useful tags, but remember that you can do so quite easily.