NAME

MooseX::Templated::Role - Role to render a Moose class with template

SYNOPSIS

Farm/Cow.pm

    package Farm::Cow;
    use Moose;
    with 'MooseX::Templated::Role';

    has 'spots'   => ( is => 'rw' );
    has 'hobbies' => ( is => 'rw', default => sub { ['mooing', 'chewing'] } );

    sub moo { "Moooooooo!" }

Farm/Cow.tt

    This cow has [% self.spots %] spots - it likes
    [% self.hobbies.join(" and ") %]. 
    [% self.moo %]!

Elsewhere on the Farm...

    my $cow = Farm::Cow->new( spots => '8' );
    
    $cow->render();
    
    # This cow has 8 spots - it likes
    # mooing and chewing.
    # Moooooooo!

Extended features

/alt/path/Farm/Cow.xml.tt2

    <cow sound="[% self.moo | html %]" spots="[% self.spots %]">
    
    [%- FOREACH hobby = self.hobbies %]
        <hobby name="[% hobby | html %]"/>
    [%- END %]
    
    </cow>

Then, back out on the farm

    $cow = Farm::Cow->new( spots => 8 );
    
    $cow->template_src_base( '/alt/path' );  # default is same as module
    $cow->template_src_ext ( '.tt2' );       # default is '.tt'

    $cow->render( 'xml' );                   # adds to file path

    # <cow sound="Moooooooo" spots="8">
    #    <hobby name="mooing"/>
    #    <hobby name="chewing"/>
    # </cow>

METHODS

render( %options )

This renders the module consuming this role and returns the output as a string. This method accepts the following optional key/values (either as %options or \%options):

source

Specifies the template source to be used for the rendering process. For flexibility, the source can be specified in a number of different ways - the intention is for it to Do What You Mean (DWYM).

How the source is interpreted will depend partly on the default options specified by the template_view_class that you are using (the default view is MooseX::Templated::View::TT). However, for consistency across your application, the recommended usage is to allow the template source to be decided by using 'shortcuts'.

Default:

    Farm::Cow->new->render()

    # CHECKS FOR:
    #   - Farm::Cow::_template()
    #   - /path/to/Farm/Cow.tt

Using shortcuts:

    Farm::Cow->new->render( source => 'xml' )
    
    # CHECKS FOR:
    #   - Farm::Cow::_template_xml()
    #   - /path/to/Farm/Cow.xml.tt

These alternatives will also work:

    Farm::Cow->new->render( source => '/other/path/cow.tt' );
    Farm::Cow->new->render( source => 'Cow goes [% self.moo %]' );

See "Setting the template source" for more information on the logic behind choosing how to interpret this string.

template_view

Provides access to the underlying MooseX::Templated::View object

template_view_class

Can be passed in the constructor to specify which MooseX::Templated::View to use.

By default this is set to use the view based on Template Toolkit:

    'template_view_class' => 'MooseX::Templated::View::TT'

However, it is entirely possible that views will be written for different templating engines in the future (contribs welcome!).

See MooseX::Templated::View for details on implementing your own view.

template_view_config( \%options )

Config options to be passed to the template view class when creating the template engine. These will be merged with any default parameters set by the view engine.

DESCRIPTION

Setting the template source

The decision process for assigning the source is indicated by first successful step in the sequence below:

render( source => "SCALAR" )

1. Internal method (shortcut)

Check if the calling module provides a method named '_template' or '_template_{TYPE}'. If so, the template source will be set from the result of that method call.

    package Farm::Cow;
    
    with 'MooseX::Templated::Role';
    
    has 'spots'    => ( is => 'rw', default => 8 );
    has 'hobbies'  => ( is => 'rw', default => sub { [ 'mooing', 'chewing' ] } );
    
    sub _template { 'Cow has [% self.spots %] spots' }
    
    sub _template_xml {
        my $self = shift;
        return <<"_XML";
    <cow spots='[% self.spots %]'>
        [% FOREACH hobby = self.hobbies %]
        <hobby name="[% hobby %]" />
        [% END %]
    </cow>
    _XML
    };
    
    1;
    
    package main;
    
    print Farm::Cow->new->render;
    # 'Cow has 8 spots'
    
    print Farm::Cow->new->render( source => 'XML' );
    # <cow spots="8">
    #   <hobby name="mooing"/>
    #   <hobby name="chewing"/>
    # </cow>

2. External file (shortcut)

Use an associated template file if it exists (see build_build_src_path for more information on how the template file path is built). This is the recommended approach as it separates the template location and content from the application code.

/path/to/lib/Farm/Cow.pm

    package Farm::Cow;
    
    with 'MooseX::Templated::Role';
    
    has 'spots'    => ( is => 'rw', default => 8 );
    has 'hobbies'  => ( is => 'rw', default => sub { [ 'mooing', 'chewing' ] } );
    

/path/to/lib/Farm/Cow.tt

    Cow has [% self.spots %] spots
    

/path/to/lib/Farm/Cow.xml.tt

    <cow spots="[% self.spots %]">
        [% FOREACH hobby = self.hobbies %]
        <hobby name="[% hobby %]" />
        [% END %]
    </cow>
    

Elsewhere...

    use Farm::Cow;
    
    print Farm::Cow->new->render;
    # 'Cow has 8 spots'
    
    print Farm::Cow->new->render( source => 'XML' );
    # <cow spots="8">
    #   <hobby name="mooing"/>
    #   <hobby name="chewing"/>
    # </cow>

3. External file

Treats the string as a path to the template source file. This is not the recommended approach as liberally scattering hardcoded file paths into your application code is most probably a bad idea.

    Farm::Cow->new->render( source => '/path/to/lib/Farm/Cow.tt' );
    # 'Cow has 2 spots'

render( source => \"SCALAR" )

Alternatively, if you pass the source as a SCALAR REF then it will be assumed to be raw template source. This is not a recommended approach, but hey - TMTOWTDI.

    Farm::Cow->new->render( source => \'Cow goes "[% self.moo %]"!' );
    # 'Cow goes "Moooooooo!"'

DEPENDENCIES

Moose, Template, Readonly, File::Slurp, File::Where

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-moosex-templated@rt.cpan.org, or through the web interface at http://rt.cpan.org.

ACKNOWLEDGEMENTS

Chris Prather (perigrin)

AUTHOR

Ian Sillitoe <isillitoe@cpan.org>

LICENCE AND COPYRIGHT

Copyright (c) 2008, Ian Sillitoe <isillitoe@cpan.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

cpanm MooseX::Templated

perl -MCPAN -e shell
install MooseX::Templated