Not a developer? Go to MovableType.com

MovableType.org
Documentation
Home / Documentation / Developer (Legacy) Plugins

Creating Template Tags

One of the most common features of a plugin is the definition of additional template tags that can be used within published blog templates that provide functionality beyond the core template tag set.

Types of Template Tags

There are three types of template tags you can create:

  • function - these tags are atomic and simply output text in place of the tag itself.
  • block - the tags can contain other tags or text that is conditionally output
  • modifier - these are not technically “tags”, but attributes that can be applied to tags that will modify the output or results of a tag just prior to being output or returned to the calling template

“Conditional Tags”

In Movable Type 3.x and prior, there was support for a specific template type called “Conditional Tags.” Movable Type calls them “block” tags, but provides a facility to define conditional block tags that function from a programmatic standpoint in the exact same way. See below.

Declaring Template Tags

To declare a plugin’s template tags you will need to augment your plugin’s init_registry subroutine. This subroutine is called automatically when the plugin is loaded by Movable Type during the initialization phase. It should specify via the plugin’s built-in “registry” function the simple data structure that should be merged with Movable Type’s core registry.

The following code sample declares four template tags:

  • <mt:SaySomething> - will output the word “Something”
  • <mt:SaySomethingElse> - will output the word “Something Else”
  • <mt:LoopTenTimes></mt:LoopTenTimes> - will output the contents contained by the tag 10 times
  • <mt:IfOdd></mt:IfOdd> - will output the contents contained by the tag only if the iteration through the loop is odd

The code:

sub init_registry {
    my $plugin = shift;
    $plugin->registry({
        tags => {
            function => {
                'SaySomething' => sub { return "Something"; },
                'SaySomethingElse' => sub { return "Something Else"; },
            },
            block => {
                'LoopTenTimes' => \&_hdlr_LoopTenTimes,
                'IfOdd?' => \&_hdlr_IfOdd,
            },
        },
    });
}

These subroutines are then called each time one of these template tags is encountered in your template code.

# A block tag with a loop
sub _hdlr_LoopTenTimes {
    my ($ctx, $args, $cond) = @_;
    my $out = "";
    my $builder = $ctx->stash('builder');
    my $tokens = $ctx->stash('tokens');
    for (my $i = 1; $i <= 10; $i++) {
        $ctx->stash("current_loop_number",$i);
        $out .= "$i - " . $builder->build($ctx,$tokens,$cond);
    }
    return $out;
}
# A Conditional Tag
sub _hdlr_IfOdd {
    my ($ctx, $args, $cond) = @_;
    my $num = $ctx->stash('current_loop_number');
    if ($num % 2 == 0) {
        return 0;
    } else {
        return 1;
    }
}

For example, the following template code:

<mt:LoopTenTimes>
  <mt:IfOdd><mt:SaySomething></mt:IfOdd>
</mt:LoopTenTimes>

Will output the following text:

1 - Something
2 - 
3 - Something
4 - 
5 - Something
6 - 
7 - Something
8 - 
9 - Something
10 -

The Template Context

When a template is being processed during the publishing process, the context is maintained while the page is processed and published. Template tags can store variables and information in the context to be used by other tags. This is the best way to maintain state during the process of publishing a page. To store or retrieve a variable, use the “stash” method.

Storing values in the stash

sub handler {
     my ($ctx, $args, $cond) = @_;
     $ctx->stash("some stash key", "some value");
}

Retrieving values from the stash

sub handler {
     my ($ctx, $args, $cond) = @_;
     my $value = $ctx->stash("some stash key");
     # do something
}

Arguments

The behavior of template tags can be modified programmatically through the use of template tag attributes. These attributes can be used to customize the output of a template tag according to the developers design. For example:

<MTEntries lastn="2" sort="created_on"></MTEntries>

In the example above, both “lastn” and “sort” are template tag attributes. Accessing the values passed to these template tags is done via the following code sample:

sub handler {
  my ($ctx, $args, $cond) = @_;
  my $lastn = $args->{lastn};
  my $sort = $args->{sort};
  # do something
}

Help URL

To add your tag to the Template Tag Docs listing on the Edit Template screen, you’ll need to add the help_url to the tags array of the registry. Shown with YAML:

tags:
    help_url: http://blah.com/tags/%t.html
    function:

%t will be replaced by the dirified tag name. Of course, you’ll also need to create a documentation page at http://blah.com/tags/%t.html for the link to work.

See Also

Back