Declaring Template Tags

All template tags are first declared in the plugin’s config.yaml file. In the following example we are going to define four different template tags to illustrate each of the following:

• How to declare a function tag
• How to declare a tag that loops
• How to declare a conditional tag that will show and hide content based upon a variable
• How to parameterize template tags to take arguments or input

Here are the tags we will define in this example:

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

Registering Your Tags

First up: your config.yaml file. The following sample shows how to register each of the four tags this example will illustrate:

name: Example Plugin for Movable Type
id: Example
description: This plugin is an example plugin for Movable Type.
version: 1.0
tags:
    function:
        SaySomething: $Example::Example::Plugin::SaySomething
        SayWhatever: $Example::Example::Plugin::SayWhatever
    block:
        LoopTenTimes: $Example::Example::Plugin::LoopTenTimes
        IfOdd?: $Example::Example::Plugin::IfOdd

Registering Conditional Tags

Conditional tags are a special kind of block tag. They work by enclosing content by an opening and closing tag, like any other block tag. However their handler (their perl code) is much simpler. A conditional tag hander need only return true or false. If the handler returns true, then the contents of the tag will be displayed. If the handler returns false then the contents of the tag will be ignored.

Conditional tags are differentiated from a normal block tag by appending a question mark ‘?’ to the tag’s name. When you do this, be sure to encapsulate the template tag in apostrophe’s or Perl might complain about a YAML syntax error.

Defining the Tag’s Behavior

Once the tags have been declared in your config.yaml it is time to write the code that will govern their behavior.

1. Create a plugin module called Plugin.pm in the following directory:

   /path/to/mt/plugins/Example/lib/Example/

2. Edit Plugin.pm and cut and paste the following into it using a text editor (don’t worry, we will deconstruct how all of this works soon enough):

   package Example::Plugin;
   use strict;
   
   
   sub SaySomething {
       my ($ctx, $args) = @_;
       return "Something";    
   }
   
   
   sub SayWhatever {
       my ($ctx, $args) = @_;
       # What the person passed in through the argument 'say'
       my $input = $args->{'say'};
       return $input;
   }
   
   
   sub LoopTenTimes {
       my ($ctx, $args, $cond) = @_;
       my $out = "";
       for (my $i = 1; $i <= 10; $i++) {
           $ctx->stash("current_loop_number",$i);
           defined(my $txt = $ctx->slurp($args,$cond)) or return;
           $out .= "$i - $txt";
       }
       return $out;
   }
   
   
   sub IfOdd {
       my ($ctx, $args, $cond) = @_;
       my $num = $ctx->stash('current_loop_number');
       if ($num % 2 == 0) {
           return 0;
       } else {
           return 1;
       }
   }
   
   
   1; # Every module must return true
   

Once this plugin has been created, the following template code can be used:

<mt:LoopTenTimes>
  <mt:IfOdd>
    <mt:SaySomething>
  <mt:Else>
    <mt:SayWhatever say="I am even!">
  </mt:IfOdd>
</mt:LoopTenTimes>

When processed through Movable Type, the above template code will output the following text:

1 - Something
2 - I am even!
3 - Something
4 - I am even!
5 - Something
6 - I am even!
7 - Something
8 - I am even!
9 - Something
10 - I am even!

Ok. We blazed through that, and we didn’t even explain the perl code at all. In the next section we will deconstruct what some of those tag handlers were doing in an effort to shed some light on Movable Type’s inner workings.