NAME

Template::Caribou::Tags - generates tags functions for Caribou templates

VERSION

version 1.2.2

SYNOPSIS

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;

DESCRIPTION

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.

Core functionality

Tag functions are created using the render_tag function. For example:

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!" };
};   

Creating ad-hoc tags

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:

package MyTemplate;

use Template::Caribou;

use Template::Caribou::Tags
    mytag => { tag => 'foo' };

# renders as '<foo>hi!</foo>'
template main => sub {
    foo { 
        "hi!";
    };
};   

EXPORTS

By default, nothing is exported. The functions render_tag and attr can be exported by this module.

Custom tag functions can also be defined via the export keyword mytag.

mytag accepts the following arguments:

tag => $name

Tagname that will be used. If not specified, defaults to div.

-as => $name

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.

groom => sub { }

Grooming function for the tag block. See render_tag for more details.

classes => \@classes

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.,

main_div { $_{class}{main} = 0; ... };

attr => \%attributes

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.

If the $inner_block is empty, the tag will be of the form <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.

AUTHOR

Yanick Champoux <yanick@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 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.

cpanm Template::Caribou

perl -MCPAN -e shell
install Template::Caribou