Template::Caribou::Tags - generates tags functions for Caribou templates
version 1.2.1
package MyTemplate; use Template::Caribou; use Template::Caribou::Tags mytag => { -as => 'foo', tag => 'p', class => 'baz' }; template bar => sub { foo { 'hello' }; }; # <p class="baz">hello</p> print __PACKAGE__->new->bar;
This module provides the tools to create tag libraries, or ad-hoc tags.
For pre-defined sets of tags, you may want to look at Template::Caribou::Tags::HTML, Template::Caribou::Tags::HTML::Extended, and friends.
Tag functions are created using the render_tag function. For example:
render_tag
package MyTemplate; use Template::Caribou; use Template::Caribou::Tags qw/ render_tag /; sub foo(&) { render_tag( 'foo', shift ) } # renders as '<foo>hi!</foo>' template main => sub { foo { "hi!" }; };
Defining a function and using render_tag is a little bulky and, typically, will only be used when creating tag libraries. In most cases, the my_tag export keyword can be used to create custom tags. For example, the previous foo definition could have been done this way:
my_tag
foo
package MyTemplate; use Template::Caribou; use Template::Caribou::Tags mytag => { tag => 'foo' }; # renders as '<foo>hi!</foo>' template main => sub { foo { "hi!"; }; };
By default, nothing is exported. The functions render_tag and attr can be exported by this module.
attr
Custom tag functions can also be defined via the export keyword mytag.
mytag
mytag accepts the following arguments:
Tagname that will be used. If not specified, defaults to div.
div
Name under which the tag function will be exported. If not specified, defaults to the value of the tag argument. At least one of -as or tag must be given explicitly.
tag
-as
Grooming function for the tag block. See render_tag for more details.
Default value for the 'class' attribute of the tag.
use Template::Caribou::Tags # <div class="main">...</div> mytag => { -as => 'main_div', classes => [ 'main' ] };
If you want to remove a default class from the tag, set its value to 0 in %_. E.g.,
0
%_
main_div { $_{class}{main} = 0; ... };
Default set of attributes for the tag.
use Template::Caribou::Tags # <input disabled="disabled">...</input> mytag => { -as => 'disabled_input', tag => 'input', attr => { disabled => 'disabled' } };
I recommend you use %_ directly instead.
Accesses the attributes of a tag within its block.
If provided an even number of parameters, sets the attributes to those values.
div { attr class => 'foo', style => 'text-align: center'; "hi there"; }; # <div class="foo" style="text-align: center">hi there</div>
Many calls to attr can be done within the same block.
div { attr class => 'foo'; attr style => 'text-align: center'; "hi there"; }; # <div class="foo" style="text-align: center">hi there</div>
To add/remove to an attribute instead of replacing its value, prefix the attribute name with a plus or minus sign. Doing either will automatically turn the value in %_ to a hashref.
div { attr class => 'foo baz'; attr '+class' => 'bar'; attr '-class' => 'baz'; "hi there"; }; # <div class="foo bar">hi there</div>
The value of an attribute can also be queried by passing a single argument to attr.
div { ...; # some complex stuff here my $class = attr 'class'; attr '+style' => 'text-align: center' if $class =~ /_centered/; ...; }
Prints out a tag in a template. The $inner_block is a string or coderef holding the content of the tag.
$inner_block
If the $inner_block is empty, the tag will be of the form <foo />.
<foo />
render_tag( 'div', 'hello' ); # <div>hello</div> render_tag( 'div', sub { 'hello' } ) # <div>hello</div> render_tag( 'div', '' ); # <div />
An optional grooming function can be passed. If it is, an hash holding the attributes of the tag, and its inner content will be passed to it as %_ and $_, respectively.
$_
# '<div>the current time is Wed Nov 25 13:18:33 2015</div>' render_tag( 'div', 'the current time is DATETIME', sub { s/DATETIME/scalar localtime/eg; }); # '<div class="mine">foo</div>' render_tag( 'div', 'foo', sub { $_{class} = 'mine' } )
An optional $indent argument can also be given. If explicitly set to false, the tag won't be indented even when the template is in pretty-print mode. Used for tags where whitespaces are significant or would alter the presentation (e.g., pre or emphasis). Defaults to true.
$indent
false
pre
emphasis
true
Yanick Champoux <yanick@cpan.org>
This software is copyright (c) 2017 by Yanick Champoux.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
2 POD Errors
The following errors were encountered while parsing the POD:
Unknown directive: =function
To install Template::Caribou, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Template::Caribou
CPAN shell
perl -MCPAN -e shell install Template::Caribou
For more information on module installation, please visit the detailed CPAN module installation guide.