Template::Liquid::Tag - Documentation for Template::Liquid's Standard Tagsets
Tags are used for the logic in your template. For a list of standard tags, see the Liquid documentation.
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.
{% for x in (1..10)%}
x in (1..10)
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.
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.
name
$markup
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.
0
30
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.
{^% dump var %}
Template::LiquidX::Tag::Dump
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.
end_tag
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 { template => $s->{template}, 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.
{% random value %}...
rand($odds)
random
{% random 1 %}
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.
'end' . $args-
In the render step, we must return the stringification of all child nodes pushed onto the stack by the parser.
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.
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/).
Copyright (C) 2009-2022 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/.
To install Template::Liquid, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Template::Liquid
CPAN shell
perl -MCPAN -e shell install Template::Liquid
For more information on module installation, please visit the detailed CPAN module installation guide.