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