NAME

Template::Caribou::Role - Caribou core engine

VERSION

version 1.2.2

SYNOPSIS

package MyTemplate;

use Template::Caribou;

has name => ( is => 'ro' );

template greetings => sub {
    my $self = shift;

    print "hello there, ", $self->name;
};

# later on...

my $template =  MyTemplate->new( name => 'Yanick' );

print $template->greetings;

DESCRIPTION

This role implements the rendering core of Caribou, which mostly deals with defining the templates of a class and calling them.

The templates

The templates are subs expected to print or return the content they are generating. Under the hood, they are snugly wrapped within a render call and turned into methods of the template class.

package MyTemplate;

use Template::Caribou;

has name => ( is => 'ro' );

template greetings => sub {
    my( $self, %args ) = @_;

    'hi there ' . $self->name . '!' x $args{excited};
};

my $bou = MyTemplate->new( name => 'Yanick' );

print $bou->greetings; 
    # prints 'hi there Yanick'

print $bou->greetings(excited => 1);
    # print 'hi there Yanick!

In addition of those arguments, the file descriptions ::STDOUT and ::RAW are locally defined. Anything printed to ::RAW is added verbatim to the content of the template, whereas something printed to STDOUT will be HTML-escaped.

If nothing has been printed at all by the template, it'll take its return value as its generated content.

# prints '<hey>'
print MyTemplate->render(sub{
    print "<hey>";
});

# prints '<hey>'
print MyTemplate->render(sub{
    print ::RAW "<hey>";
});

# prints 'onetwo'
print MyTemplate->render(sub{
    print "one";
    print "two";
});

# prints 'one'
print MyTemplate->render(sub{
    print "one";
    return "ignored";
});

# prints 'no print, not ignored'
print MyTemplate->render(sub{
    return "no print, not ignored";
});

Template methods can, of course, be called within other template methods. When invoked from within a template, their content is implicitly printed to ::RAW.

template outer => sub {
    my $self = shift;

    say 'alpha';
    $self->inner;
    say 'gamma';
};

template inner => sub {
    say 'beta';
};

...;

print $bou->outer; # prints 'alpha beta gamma'

Definiting templates via template instances

Templates are usually defined for the class via the template keyword. template can also be used as a method. By default, though, it'll die as adding a template that way will not only add it to the instance, but for to class itself, which is probably more than you bargained for.

$bou->template( foo => sub { ... } );
# dies with 'can only add templates from instances created 
# via 'anon_instance' or with the attribute 'can_add_templates'

If you want to add a template to a single instance, use the class method anon_instance, which will create a singleton class inheriting from the main template class.

my $bou = MyTemplate->anon_instance( name => 'Yanick' );

$bou->template( foo => sub { ... } ); # will work

Or if you really want to augment the whole class with new templates, you can set the can_add_templates attribute of the object to true.

$bou->can_add_templates(1); 
$bou->template( foo => sub { ... } ); # will work too

METHODS

new

my $bou = MyTemplate->new(
    indent            => 1,
    can_add_templates => 0,
);

indent => $boolean

If set to a true value, the nested tags rendered inside the templates will be indented. Defaults to true.

can_add_templates

If templates can be added to the class via the method invocation of template.

indent

$bou->indent($bool);

Accessor to the indent attribute. Indicates if the tags rendered within the templates should be pretty-printed with indentation or not.

can_add_templates

$bou->can_add_templates($bool);

Accessor. If set to true, allows new templates to be defined for the class via the template method.

template( $name => sub { ... } )

Defines the template $name. Will trigger an exception unless can_add_templates was set to true or the object was created via anon_instance.

Warnings will be issued if the template redefines an already-existing function/method in the namespace.

anon_instance(@args_for_new)

Creates an anonymous class inheriting from the current one and builds an object instance with the given arguments. Useful when wanting to define templates for one specific instance.

render

$bou->render( $coderef, @template_args );
$bou->render( $template_name, @template_args );

Renders the given $coderef as a template, passing it the @template_args, and returns its generated output.

print $bou->render( sub {
    my( $self, $name ) = @_;

    'hi ' . $name . "\n";
}, $_ ) for @friends; 

The template can also be given by name.

template foo => sub { ... };

# later on

$bou->render( 'foo', @args );

# which is equivalent to

$bou->foo(@args);

get_render

Like render, but always return the generated template content, even when called inside a template.

template foo => sub { 'foo' };
template bar => sub { 'bar' };

print $bou->render(sub{
    my $self = shift;

    $self->foo;
    my $bar = $self->get_render(sub{ $self->bar });
    $bar =~  y/r/z/;
    say $bar;
});

# prints 'foobaz'

SEE ALSO

http://babyl.dyndns.org/techblog/entry/caribou - The original blog entry introducing Template::Caribou.

Template::Declare

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