Using Add-Ons

General ways that add-ons are used.

Each add-on will have its own goals and ways of doing things, but we can give you a general overview of what to expect.

Plugins

Plugins create new tags for you to use in your template. You’ll want to refer to the add-on’s documentation for the specific tags that can be used, as well as the parameters that can be used within those tags, but what follows it the general idea.

As an example, let’s say you’ve installed the animal add-on. This add-on comes with a tag to display an animal at random, called {{ animal:random }}, which will be replaced with the name of a random animal.

You might include this in your template like so:

<p>
    I was walking through the woods, when all of a sudden I was
    attacked. But this was no mere critter, this was a behemoth
    of a beast. ’Twas a {{ animal:random }}!
</p>

Plugins can also be tag-pairs. Perhaps our animal add-on lets you display a list of all known animals with the {{ animal:list_all }} tag, along with a check to see if each animal eats people. Plugins can define variables that can be used between tag-pairs. For this example, let’s assume this tag has the name of the animal in the {{ name }} tag, and a boolean in the {{ eats_people }} tag.

You could run through this list like so:

<h2>Known Animals</h2>

<ul>
    {{ animals:list_all }}
        <li>
            {{ name }},
            {{ if eats_people }}
                eats people
            {{ else }}
                doesn't eat people
            {{ endif }}
        </li>
    {{ /animals:list_all }}
</ul>

Setting Parameters

Plugins can also let you configure them by setting parameters on the tag itself. Perhaps we could limit the types of animals to list using a parameter on the {{ animal:list_by_region }} tag.

That might look like this:

<dl>
    <dt>Animals in the polar region</dt>
    <dd>
        {{ animal:list_by_region region="polar" }}
            {{ name }}{{ if !last }}, {{ endif }}
        {{ /animal:list_by_region }}
    </dd>
</dl>

The only limit to the parameters used is the number of options given to you by the add-on developer.

Fieldtypes

Fieldtypes let you define new ways to enter content into the Control Panel. Each fieldtype will come with its own list of configurations, and those configurations are generally customizable per use of the field. This lets you use the same fieldtype over and over again, and potentially vastly changing the way it’s displayed or used.

To continue our example from above, let’s say that the animal add-on comes with its own fieldtype for designating animals. Using this fieldtype might look like this in a fieldset:

title: Species
fields:
  title:
    instructions: Name this species.
  animal:
    type: animal
    display: Animal
    instructions: Name this animal, and assign it a region.
  content:
    type: hidden

How this field displays within your Control Panel is completely up to the developer. This fieldtype might display a text box for the name of your animal, along with a drop-down of allowed regions.

As with Plugins, you’ll want to consult each add-on’s documentation to see if it has a fieldtype and if it does, how to use it in the control panel.