NAME

Template::Liquid::Tag - Documentation for Template::Liquid's Standard Tagsets

Description

Tags are used for the logic in your template. For a list of standard tags, see the Liquid documentation.

Extending the Basic Liquid Syntax with Custom Tags

To create a new tag, simply inherit from Template::Liquid::Tag and register your block globally.

For a complete example of this, keep reading. To see real world examples, check out Template::LiquidX::Tag::Include and Template::LiquidX::Tag::Dump on CPAN.

Your constructor should expect the following arguments:

$class

...you know what to do with this.

$args

This is a hash ref which contains these values (at least)

attrs

The attributes within the tag. For example, given {% for x in (1..10)%}, you would find x in (1..10) in the attrs value.

parent

The direct parent of this new node.

markup

The tag as it appears in the template. For example, given {% for x in (1..10)%}, the full markup would be {% for x in (1..10)%}.

tag_name

The name of the current tag. For example, given {% for x in (1..10)%}, the tag_name would be for.

template

A quick link back to the top level template object.

Your object should at least contain the parent and template values handed to you in $args. For completeness, you should also include a name (defined any way you want) and the $markup and tag_name from the $args variable.

Enough jibba jabba... the next few sections show actual code...

    package Template::LiquidX::Tag::Random;
    use base 'Template::Liquid::Tag';
    sub import { Template::Liquid::register_tag('random') }

    sub new {
        my ($class, $args) = @_;
        $args->{'attrs'} ||= 50;
        my $s = bless {
                          max      => $args->{'attrs'},
                          name     => 'rand-' . $args->{'attrs'},
                          tag_name => $args->{'tag_name'},
                          parent   => $args->{'parent'},
                          template => $args->{'template'},
                          markup   => $args->{'markup'}
        }, $class;
        return $s;
    }

    sub render {
        my ($s) = @_;
        return int rand $s->{template}{context}->get($s->{'max'});
    }
    1;

Using this new tag is as simple as...

    use Template::Liquid;
    use Template::LiquidX::Tag::Random;

    print Template::Liquid->parse('{% random max %}')->render(max => 30);

This will print a random integer between 0 and 30.

User-defined, Balanced (Block-like) Tags

If you just want a quick sample, you'll find an example {^% dump var %} tag bundled as a separate dist named Template::LiquidX::Tag::Dump on CPAN.

Block-like tags are very similar to simple. Inherit from Template::Liquid::Tag and register your block globally.

The only difference is you define an end_tag in your object.

Here's an example...

    package Template::LiquidX::Tag::Random;
    use base 'Template::Liquid::Tag';
    sub import { Template::Liquid::register_tag('random') }

    sub new {
        my ($class, $args) = @_;
        raise Template::Liquid::Error {
                   type    => 'Syntax',
                   message => 'Missing argument list in ' . $args->{'markup'},
                   fatal   => 1
            }
            if !defined $args->{'attrs'} || $args->{'attrs'} !~ m[\S$]o;
        my $s = bless {odds     => $args->{'attrs'},
                       name     => 'Rand-' . $args->{'attrs'},
                       tag_name => $args->{'tag_name'},
                       parent   => $args->{'parent'},
                       template => $args->{'template'},
                       markup   => $args->{'markup'},
                       end_tag  => 'end' . $args->{'tag_name'}
        }, $class;
        return $s;
    }

    sub render {
        my $s      = shift;
        my $return = '';
        if (!int rand $s->{template}{context}->get($s->{'odds'})) {
            for my $node (@{$s->{'nodelist'}}) {
                my $rendering = ref $node ? $node->render() : $node;
                $return .= defined $rendering ? $rendering : '';
            }
        }
        $return;
    }
    1;

Using this example tag...

    use Template::Liquid;
    use Template::LiquidX::Tag::Random;

    print Template::Liquid->parse(q[{% random 2 %}Now, that's money well spent!{% endrandom %}])->render();

In this example, we expect a single argument. During the render stage, we resolve the variable (this allows for constructs like: {% random value %}...) and depending on a call to rand($odds) the tag either renders to an empty string or we continue to render the child nodes. Here, our random tag prints only 50% of the time, {% random 1 %} would work every time.

The biggest changes between this and the random tag we build above are in the constructor.

The extra end_tag attribute in the object's reference lets the parser know that this is a block that will slurp until the end tag is found. In our example, we use 'end' . $args-{'tag_name'}> because you may eventually subclass this tag and let it inherit this constructor. Now that we're sure the parser knows what to look for, we go ahead and continue parsing the list of tokens. The parser will shove child nodes (tags, variables, and simple strings) onto your stack until the end_tag is found.

In the render step, we must return the stringification of all child nodes pushed onto the stack by the parser.

Creating Your Own Conditional Tag Blocks

The internals are still kinda rough around this bit so documenting it is on my TODO list. If you're a glutton for punishment, I guess you can skim the source for the if tag and its subclass, the unless tag.

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

The original Liquid template system was developed by jadedPixel (http://jadedpixel.com/) and Tobias Lütke (http://blog.leetsoft.com/).

License and Legal

Copyright (C) 2009-2012 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or http://www.perlfoundation.org/artistic_license_2_0. For clarification, see http://www.perlfoundation.org/artistic_2_0_notes.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See http://creativecommons.org/licenses/by-sa/3.0/us/legalcode. For clarification, see http://creativecommons.org/licenses/by-sa/3.0/us/.

cpanm Template::Liquid

perl -MCPAN -e shell
install Template::Liquid