NAME

Dancer2::Template::Mason - Mason wrapper for Dancer2

VERSION

version 0.1.2

SYNOPSIS

 # in 'config.yml'
 template: 'mason'

 # in the app

 get '/foo', sub {
   template 'foo' => {
       title => 'bar'
   };
 };

Then, on views/foo.mason:

<%args>
$title
</%args>

<h1><% $title %></h1>

<p>Mason says hi!</p>

DESCRIPTION

This class is an interface between Dancer's template engine abstraction layer and the HTML::Mason templating system. For templates using Mason version 2.x, what you want is Dancer2::Template::Mason2.

In order to use this engine, set the template to 'mason' in the configuration file:

template: mason

HTML::Mason::Interp CONFIGURATION

Parameters can also be passed to the HTML::Mason::Interp interpreter via the configuration file, like so:

engines:
    mason:
        default_escape_flags: ['h']

If unspecified, comp_root defaults to the views configuration setting or, if it's undefined, to the /views subdirectory of the application.

Dancer2 Tokens and Mason Parameters

As with other template adapters, Dancer2 passes the following to your templates automatically:

• perl_version

• dancer_version

• settings

• request

• params

• vars

• session

(see Dancer2::Core::Role::Template for more details)

Content you pass via the template keyword creates another token, content.

To access them in your Mason templates, you have options. To use these tokens in the most explicit way possible, declare %args in your Mason template as such:

<%args>
$perl_version
$dancer_version
$settings
$request
$params
$vars
$session
</%args>

You can then pass them explicitly to other components:

<& /components/topbar.m, title => $title, session => $session &>

For the lazy, all tokens are passed via Mason as %ARGS. You can reference them as keys of this hash:

% my $session = $ARGS{ session };
<h1>Hello, <% $session->{ username } %>!</h1>

For the really lazy, rather than build a list of parameters to pass other components, you can simply pass the entire %ARGS hash:

<& /components/topbar.m, %ARGS &>

See https://metacpan.org/dist/HTML-Mason/view/lib/HTML/Mason/Devel.pod#PASSING-PARAMETERS for more information about passing parameters to components.

Notes on Mason Caching and Performance

To improve performance of your templates, Mason creates a long-term cache on disk. This is great in production, where you want to squeak every ounce of performance out of your application, but in development, it can be a pain to constantly clear the cache. And when developing, it's not always clear where Mason even stores the cache!

For development, we recommend disabling the Mason cache. In your environments/development.yml file, you'd put the following:

template: "mason"
engines:
  template:
    mason:
      use_object_files: 0
      static_source: 0

(static_source is also a potential performance enhancing setting. See the Mason docs for more details)

In production (environments/production.yml), recommended settings are:

template: "mason"
engines:
  template:
    mason:
      extension: m
      data_dir: "/path/to/your/app/var/"
      use_object_files: 1
      static_source: 1

data_dir tells Mason where to store its long-term cache. It must be an absolute path.

Clearing the cache is as easy as:

rm -rf /path/to/your/app/var/obj

See the Mason docs for more information on the object files and caching.

SEE ALSO

Dancer2, HTML::Mason.

For Mason v2, see Mason and Dancer2::Template::Mason2.

And, of course, there is the original Dancer::Template::Mason.

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 Dancer2::Template::Mason

perl -MCPAN -e shell
install Dancer2::Template::Mason