NAME

MooseX::Templated::Engine - connects MooseX::Templated object to template

SYNOPSIS

Internal docs - see MooseX::Templated for usage.

    my $engine = MooseX::Templated::Engine->new(
      model                => My::Module->new( ... ),
      view_class           => 'MooseX::Templated::View::TT',
      view_config          => \%config,
      template_suffix      => '.tt',
      template_root        => '__LIB__/root/src',
      template_method_stub => '_template',
    );

    $engine->render();
    # source:
    #   @INC/root/src/My/Module.tt
    #   My::Module::_template

    $engine->render( source => "xml" );
    # source:
    #   @INC/root/src/My/Module.xml.tt
    #   My::Module::_template_xml

    $engine->render( source => "/path/to/file.ext" );
    # source:
    #   /path/to/file.ext

    $engine->render( source => \"[% template %]" );
    # source:
    #   <inline>

render()

render( source => $source )

get_source()

get_source( $shortcut )

get_source( \$template )

A shortcut is a simple string such as "xml".

Called from the module Farm::Cow, this will attempt to find the file:

  @INC/Farm/Cow.xml.tt

based on:

  ${template_root}/Farm/Cow.${shortcut}.${template_suffix}

Otherwise it will check with the calling object has a method:

  Farm::Cow::_template_xml

build_src_path( %options )

Builds the default filename to be used the template source

    Farm::Cow => /path/to/Farm/Cow.tt

    template_root      class_name    template_suffix
    /path/to/          Farm/Cow      .tt

options

Explicitly passed options override defaults

'root' => '/alt/path'

'suffix' => '.ext'

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.

view

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

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:

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

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.

DEPENDENCIES

Moose, Template, Readonly, File::Slurp

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