# NAME

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

# VERSION

version 0.1.2

# SYNOPSIS

```perl
 # 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](https://metacpan.org/pod/HTML%3A%3AMason) templating system. 
For templates using [Mason](https://metacpan.org/pod/Mason) version
2.x, what you want is [Dancer2::Template::Mason2](https://metacpan.org/pod/Dancer2%3A%3ATemplate%3A%3AMason2).

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](https://metacpan.org/pod/HTML%3A%3AMason%3A%3AInterp) 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](https://metacpan.org/pod/Dancer2%3A%3ACore%3A%3ARole%3A%3ATemplate) 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:

```perl
<& /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:

```perl
% 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](https://metacpan.org/pod/the%20Mason%20Developer%27s%20Manual)
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:

```perl
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](https://metacpan.org/dist/HTML-Mason/view/lib/HTML/Mason/Admin.pod#Static-Source-Mode)
for more details)

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

```perl
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](https://metacpan.org/dist/HTML-Mason/view/lib/HTML/Mason/Admin.pod#Object-Files)
for more information on the object files and caching.

# SEE ALSO

[Dancer2](https://metacpan.org/pod/Dancer2), [HTML::Mason](https://metacpan.org/pod/HTML%3A%3AMason).

For Mason v2, see [Mason](https://metacpan.org/pod/Mason) and [Dancer2::Template::Mason2](https://metacpan.org/pod/Dancer2%3A%3ATemplate%3A%3AMason2).

And, of course, there is the original [Dancer::Template::Mason](https://metacpan.org/pod/Dancer%3A%3ATemplate%3A%3AMason).

# AUTHOR

Yanick Champoux <yanick@cpan.org> [![endorse](http://api.coderwall.com/yanick/endorsecount.png)](http://coderwall.com/yanick)

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

# POD ERRORS

Hey! **The above document had some coding errors, which are explained below:**

- Around line 116:

    alternative text 'https://metacpan.org/dist/HTML-Mason/view/lib/HTML/Mason/Devel.pod#PASSING-PARAMETERS' contains non-escaped | or /