package Solution::Tag;
{
use strict;
use warnings;
our @ISA = qw[Solution::Document];
our $VERSION = '0.9.1';
sub tag { return $_[0]->{'tag_name'}; }
sub end_tag { return $_[0]->{'end_tag'} || undef; }
sub conditional_tag { return $_[0]->{'conditional_tag'} || undef; }
# Should be overridden by child classes
sub new {
return Solution::StandardError->new(
'Please define a constructor in ' . $_[0]);
}
sub push_block {
return Solution::StandardError->(
'Please define a push_block method (for conditional tags) in '
. $_[0]);
}
}
1;
=pod
=head1 NAME
Solution::Tag - Documentation for Solution's Standard and Custom Tagset
=head1 Description
Tags are used for the logic in your L<template|Solution::Template>. New tags
are very easy to code, so I hope to get many contributions to the standard tag
library after releasing this code.
=head1 Standard Tagset
Expanding the list of supported tags is easy but here's the current standard
set:
=head2 C<comment>
Comment tags are simple blocks that do nothing during the
L<render|Solution::Template/"render"> stage. Use these to temporarily disable
blocks of code or do insert documentation into your source code.
This is a {% comment %} secret {% endcomment %}line of text.
For more, see L<Solution::Tag::Comment|Solution::Tag::Comment>.
=head2 C<if> / C<elseif> / C<else>
{% if post.body contains search_string %}
<div class="post result" id="p-{{post.id}}">
<p class="title">{{ post.title }}</p>
...
</div>
{% endunless %}
=head2 C<unless> / C<elseif> / C<else>
This is sorta the opposite of C<if>.
{% unless some.value == 3 %}
Well, the value sure ain't three.
{% elseif some.value > 1 %}
It's greater than one.
{% else %}
Well, is greater than one but not equal to three.
Psst! It's {{some.value}}.
{% endunless %}
For more, see L<Solution::Tag::Unless|Solution::Tag::Unless>.
=head2 C<case>
TODO
=head2 C<cycle>
TODO
=head2 C<for>
TODO
=head2 C<assign>
TODO
=head2 C<capture>
TODO
=head2 C<include>
TODO
=head1 Extending Solution with Custom Tags
To create a new tag, simply inherit from L<Solution::Tag|Solution::Tag> and
register your block L<globally|Solution/"Solution->register_tag( ... )"> or
locally with L<Solution::Template|Solution::Template/"register_tag">.
Your constructor should expect the following arguments:
=over 4
=item C<$class>
...you know what to do with this.
=item C<$args>
This is a hash ref which contains these values (at least)
=over 4
=item C<attrs>
The attributes within the tag. For example, given C<{% for x in (1..10)%}>,
you would find C<x in (1..10)> in the C<attrs> value.
=item C<parent>
The direct parent of this new node.
=item C<markup>
The tag as it appears in the template. For example, given
C<{% for x in (1..10)%}>, the full C<markup> would be
C<{% for x in (1..10)%}>.
=item C<tag_name>
The name of the current tag. For example, given C<{% for x in (1..10)%}>, the
C<tag_name> would be C<for>.
=item C<template>
A quick link back to the top level template object.
=back
=back
Your object should at least contain the C<parent> and C<template> values
handed to you in C<$args>. For completeness, you should also include a C<name>
(defined any way you want) and the C<$markup> and C<tag_name> from the
C<$args> variable.
Enough jibba jabba... here's some functioning code...
package SolutionX::Tag::Random;
use strict;
use warnings;
our @ISA = qw[Solution::Tag];
Solution->register_tag('random') if $Solution::VERSION;
sub new {
my ($class, $args) = @_;
$args->{'attrs'} ||= 50;
my $self = bless {
max => $args->{'attrs'},
name => 'rand-' . $args->{'attrs'},
tag_name => $args->{'tag_name'},
parent => $args->{'parent'},
template => $args->{'template'},
markup => $args->{'markup'}
}, $class;
return $self;
}
sub render {
my ($self) = @_;
return int rand $self->resolve($self->{'max'});
}
1;
Using this new tag is as simple as...
use Solution;
use SolutionX::Tag::Random;
print Solution::Template->parse('{% random max %}')->render({max => 30});
This will print a random integer between C<0> and C<30>.
=head2 Creating Your Own Tag Blocks
If you just want a quick sample, see C<examples/custom_tag.pl>. There you'll
find an example C<{^% dump var %}> tag named C<SolutionX::Tag::Dump>.
Block-like tags are very similar to
L<simple|Solution::Tag/"Create Your Own Tags">. Inherit from
L<Solution::Tag|Solution::Tag> and register your block
L<globally|Solution/"register_tag"> or locally with
L<Solution::Template|Solution::Template/"register_tag">.
The only difference is you define an C<end_tag> in your object.
Here's an example...
package SolutionX::Tag::Large::Hadron::Collider;
use strict;
use warnings;
our @ISA = qw[Solution::Tag];
Solution->register_tag('lhc') if $Solution::VERSION;
sub new {
my ($class, $args) = @_;
my $self = bless {
odds => $args->{'attrs'},
name => 'LHC-' . $args->{'attrs'},
tag_name => $args->{'tag_name'},
parent => $args->{'parent'},
template => $args->{'template'},
markup => $args->{'markup'},
end_tag => 'end' . $args->{'tag_name'}
}, $class;
return $self;
}
sub render {
my ($self) = @_;
return if int rand $self->resolve($self->{'odds'});
return join '', @{$self->{'nodelist'}};
}
1;
Using this example tag...
use Solution;
use SolutionX::Tag::Large::Hadron::Collider;
warn Solution::Template->parse(q[{% lhc 2 %}Now, that's money well spent!{% endlhc %}])->render();
Just like the real thing, our C<lhc> tag works only 50% of the time.
The biggest changes between this and the
L<random tag|Solution/"Create Your Own Tags"> we build above are in the
constructor.
The extra C<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 C<'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
L<parsing|Solution::Template/"parse"> the list of tokens. The parser will shove
child nodes (L<tags|Solution::Tag>, L<variables|Solution::Variable>, and
simple strings) onto your stack until the C<end_tag> is found.
In the render step, we must return the stringification of all child nodes
pushed onto the stack by the parser.
=head2 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 L<if tag|Solution::Tag::If> and its subclass, the
L<unless tag|Solution::Tag::Unless>.
=head1 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/).
=head1 License and Legal
Copyright (C) 2009-2012 by Sanko Robinson E<lt>sanko@cpan.orgE<gt>
This program is free software; you can redistribute it and/or modify it under
the terms of The Artistic License 2.0. See the F<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/.
=cut