<<

NAME

MT::Template::Context - Movable Type Template Context

SYNOPSIS

    use MT::Template::Context;
    MT::Template::Context->add_tag( FooBar => sub {
        my($ctx, $args) = @_;
        my $foo = $ctx->stash('foo')
            or return $ctx->error("No foo in context");
        $foo->bar;
    } );

    ## In a template:
    ## <$MTFooBar$>

DESCRIPTION

MT::Template::Context provides the implementation for all of the built-in template tags in Movable Type, as well as the public interface to the system's plugin interface.

This document focuses only on the public methods needed to implement plugins in Movable Type, and the methods that plugin developers might wish to make use of. Of course, plugins can make use of other objects loaded from the Movable Type database, in which case you may wish to look at the documentation for the classes in question (for example, MT::Entry).

USAGE

MT::Template::Context->add_tag($name, \&subroutine)

add_tag registers a simple "variable tag" with the system. An example of such a tag might be <$MTEntryTitle$>.

$name is the name of the tag, without the MT prefix, and \&subroutine a reference to a subroutine (either anonymous or named). \&subroutine should return either an error (see "ERROR HANDLING") or a defined scalar value (returning undef will be treated as an error, so instead of returning undef, always return the empty string instead).

For example:

    MT::Template::Context->add_tag(ServerUptime => sub { `uptime` });

This tag would be used in a template as <$MTServerUptime$>.

The subroutine reference will be passed two arguments: the MT::Template::Context object with which the template is being built, and a reference to a hash containing the arguments passed in through the template tag. For example, if a tag <$MTFooBar$> were called like

    <$MTFooBar baz="1" quux="2"$>

the second argument to the subroutine registered with this tag would be

    {
        'quux' => 2,
        'bar' => 1
    };

MT::Template::Context->add_container_tag($name, \&subroutine)

Registers a "container tag" with the template system. Container tags are generally used to represent either a loop or a conditional. In practice, you should probably use add_container_tag just for loops--use add_conditional_tag for a conditional, because it will take care of much of the backend work for you (most conditional tag handlers have a similar structure).

$name is the name of the tag, without the MT prefix, and \&subroutine a reference to a subroutine (either anonymous or named). \&subroutine should return either an error (see "ERROR HANDLING") or a defined scalar value (returning undef will be treated as an error, so instead of returning undef, always return the empty string instead).

The subroutine reference will be passed two arguments: the MT::Template::Context object with which the template is being built, and a reference to a hash containing the arguments passed in through the template tag.

Since a container tag generally represents a loop, inside of your subroutine you will need to use a loop construct to loop over some list of items, and build the template tags used inside of the container for each of those items. These inner template tags have already been compiled into a list of tokens. You need only use the MT::Builder object to build this list of tokens into a scalar string, then add the string to your output value. The list of tokens is in $ctx->stash('tokens'), and the MT::Builder object is in $ctx->stash('builder').

For example, if a tag <MTLoop> were used like this:

    <MTLoop>
    The value of I is: <$MTLoopIValue$>
    </MTLoop>

a sample implementation of this set of tags might look like this:

    MT::Template::Context->add_container_tag(Loop => sub {
        my $ctx = shift;
        my $res = '';
        my $builder = $ctx->stash('builder');
        my $tokens = $ctx->stash('tokens');
        for my $i (1..5) {
            $ctx->stash('i_value', $i);
            defined(my $out = $builder->build($ctx, $tokens))
                or return $ctx->error($builder->errstr);
            $res .= $out;
        }
        $res;
    });

    MT::Template::Context->add_tag(LoopIValue => sub {
        my $ctx = shift;
        $ctx->stash('i_value');
    });

<$MTLoopIValue$> is a simple variable tag. <MTLoop> is registered as a container tag, and it loops over the numbers 1 through 5, building the list of tokens between <MTLoop> and </MTLoop> for each number. It checks for an error return value from the $builder->build invocation each time through.

Use of the tags above would produce:

    The value of I is: 1
    The value of I is: 2
    The value of I is: 3
    The value of I is: 4
    The value of I is: 5

MT::Template::Context->add_conditional_tag($name, $condition)

Registers a conditional tag with the template system.

Conditional tags are technically just container tags, but in order to make it very easy to write conditional tags, you can use the add_conditional_tag method. $name is the name of the tag, without the MT prefix, and $condition is a reference to a subroutine which should return true if the condition is true, and false otherwise. If the condition is true, the block of tags and markup inside of the conditional tag will be executed and displayed; otherwise, it will be ignored.

For example, the following code registers two conditional tags:

    MT::Template::Context->add_conditional_tag(IfYes => sub { 1 });
    MT::Template::Context->add_conditional_tag(IfNo => sub { 0 });

<MTIfYes> will always display its contents, because it always returns 1; <MTIfNo> will never display is contents, because it always returns 0. So if these tags were to be used like this:

    <MTIfYes>Yes, this appears.</MTIfYes>
    <MTIfNo>No, this doesn't appear.</MTIfNo>

Only "Yes, this appears." would be displayed.

A more interesting example is to add a tag <MTEntryIfTitle>, to be used in entry context, and which will display its contents if the entry has a title.

    MT::Template::Context->add_conditional_tag(EntryIfTitle => sub {
        my $e = $_[0]->stash('entry') or return;
        defined($e->title) && $e->title ne '';
    });

To be used like this:

    <MTEntries>
    <MTEntryIfTitle>
    This entry has a title: <$MTEntryTitle$>
    </MTEntryIfTitle>
    </MTEntries>

MT::Template::Context->add_global_filter($name, \&subroutine)

Registers a global tag attribute. More information is available in the Movable Type manual, in the Template Tags section, in "Global Tag Attributes".

Global tag attributes can be used in any tag, and are essentially global filters, used to filter the normal output of the tag and modify it in some way. For example, the lower_case global tag attribute can be used like this:

    <$MTEntryTitle lower_case="1"$>

and will transform all entry titles to lower-case.

Using add_global_filter you can add your own global filters. $name is the name of the filter (this should be lower-case for consistency), and \&subroutine is a reference to a subroutine that will be called to transform the normal output of the tag. \&subroutine will be given three arguments: the standard scalar output of the tag, the value of the attribute (1 in the above lower_case example), and the MT::Template::Context object being used to build the template.

For example, the following adds a rot13 filter:

    MT::Template::Context->add_global_filter(rot13 => sub {
        (my $s = shift) =~ tr/a-zA-Z/n-za-mN-ZA-M/;
        $s;
    });

Which can be used like this:

    <$MTEntryTitle rot13="1"$>

Another example: if we wished to implement the built-in trim_to filter using add_global_filter, we would use this:

    MT::Template::Context->add_global_filter(trim_to => sub {
        my($str, $len, $ctx) = @_;
        $str = substr $str, 0, $len if $len < length($str);
        $str;
    });

The second argument ($len) is used here to determine the length to which the string ($str) should be trimmed.

Note: If you add multiple global filters, the order in which they are called is undefined, so you should not rely on any particular ordering.

$ctx->stash($key [, $value ])

A simple data stash that can be used to store data between calls to different tags in your plugin. For example, this is very useful when implementing a container tag, as we saw above in the implementation of <MTLoop>.

$key should be a scalar string identifying the data that you are stashing. $value, if provided>, should be any scalar value (a string, a number, a reference, an object, etc).

When called with only $key, returns the stashed value for $key; when called with both $key and $value, sets the stash for $key to $value.

ERROR HANDLING

If an error occurs in one of the subroutine handlers within your plugin, you should return an error by calling the error method on the $ctx object:

    return $ctx->error("the error message");

In particular, you might wish to use this if your tag expects to be called in a particular context. For example, the <$MTEntry*$> tags all expect that when they are called, an entry will be in context. So they all use

    my $entry = $ctx->stash('entry')
        or return $ctx->error("Tag called without an entry in context");

to ensure this.

AUTHOR & COPYRIGHT

Please see the MT manpage for author, copyright, and license information.

<<