Ian Sillitoe > MooseX-Templated-0.02-1 > MooseX::Templated::Role



Annotate this POD


Open  0
View/Report Bugs
Source   Latest Release: MooseX-Templated-0.03


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



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

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

    sub moo { "Moooooooo!" }


    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' );
    # This cow has 8 spots - it likes
    # mooing and chewing.
    # Moooooooo!

Extended features


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

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>


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):


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



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

Using shortcuts:

    Farm::Cow->new->render( source => 'xml' )
    #   - 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.


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


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.


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 %]
    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.


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


    Cow has [% self.spots %] spots


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


    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!"'


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


None reported.


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.


Chris Prather (perigrin)


Ian Sillitoe <isillitoe@cpan.org>


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.

syntax highlighting: