[Catalyst-dev] RFC: Catalyst::View::Mason::Templated

[Sebastian Willert]

Hi again,

I found myself in a Catalyst coding spree lately (or rather in a
packaging spree for quite old code) so I present my second request for
comments tonight. I use HTML::Mason extensively for most of my projects
and was not really satisfied with the amount of features accessible
through Catalyst::View::Mason so I whipped up my own some time ago.

I choose to start virtually from scratch because Catalyst::View::Mason
took some IMO unfortunate design and API decisions early in the modules
lifetime that are really hard to correct without introducing a slew of
backcompat config options (see the INCOMPATIBILITIES section of the
POD). Catalyst::View::Templated came along recently and provided a good
excuse to package and possibly release a Mason view that is based upon
that module.

Here's the POD, so please tell me what you think.

Cheers,
  Sebastian

---

NAME
  Catalyst::View::Mason::Templated - Full featured Mason View Class

SYNOPSIS
    # use the helper
    script/create.pl view Mason Mason::Templated

    # lib/MyApp/View/Mason.pm
    package MyApp::View::Mason;

    use base 'Catalyst::View::Mason::Templated';

    1;

    $c->forward('MyApp::View::Mason');

DESCRIPTION
  Want to use a Mason component in your views? No problem!
  Catalyst::View::Mason::Templated comes to the rescue.

EXAMPLE
  From the Catalyst controller:

    $c->stash->{name} = 'Homer'; # Pass a scalar
    $c->stash->{extra_info} = {
           last_name => 'Simpson',
           children => [qw(Bart Lisa Maggie)]
    }; # A ref works too

  From the Mason template:

    <%args>
    $name
    $extra_info
    </%args>
    <p>Your name is <strong><% $name %>
      <% $extra_info->{last_name} %></strong>
    <p>Your children are:
    <ul>
    % foreach my $child (@{$extra_info->{children}}) {
    <li>$child
    % }
    </ul>

OVERWRITTEN METHODS
  new( $c, ?$args )
  Parses the mason config and builds a valid "comp_root" out of the
  "INCLUDE_PATH" config variable.

ADDITIONAL METHODS
  fetch_comp( $template )
  Returns an HTML::Mason::Component instance for the given
  template path.
  Mason templates are compiled to full fledged perl modules with
  introspection capabilities and other potential usefull stuff so this
  method is provided here even if using it breaks API compatibility with
  Catalyst::View::Templated.

MASON CONFIGURATION
  This allows you to to pass additional settings to the
  HTML::Mason::Interp constructor or to set the options as below:

  "DATA_DIR"
    Defaults to "File::Spec->tmpdir"

  "ALLOW_GLOBALS"
    Defaults to "qw/$c $name $base/"

    If you add additional allowed globals those will be prepended to the
    list of default globals.

  Most of the parameters listet in HTML::Mason::Params are also present
  (preverably in uppercase), so you can e.g. use your custom request
  class.

VIEW CONFIGURATION
  "CHARSET"
    HTML::Mason isn't bothered with character encodings so you can use
    this to set the correct charset for the output string. Setting
    "CHARSET" will force a

      Enocde::decode( $self->{CHARSET}, [...] )

    on the Mason output, thus allowing Catalyst::View::Templated to
    guess the correct content-type.

  "INCLUDE_PATH"
    An array ref containing the user's desired include paths. This is
    set to a reasonable default ("root/") if the user omits it from his
    config. HTML::Mason forces you to name your include paths if more
    than one path is given. If you want to state the path keys
    explicitly, it should be of the following form:

       MyApp->config->{View::Mason}
       = { INCLUDE_PATH  =>
         [ [ FOO => '/usr/local/foo' ],
           [ BAR => '/usr/local/bar' ] ]
         };

    If no path keys are given, they are calculated from the significant
    (i.e. unique) suffix of the path, with the first path always mapped
    to "MAIN". This example should give you correct idea:

       MyApp->config->{View::Mason}
       = { INCLUDE_PATH  =>
         [ '/usr/local/foo', '/usr/local/foo/widgets',
           '/usr/local/bar', '/usr/local/bar/widgets' ],
         };

    gets transformed to:

       MyApp->config->{View::Mason}
       = { INCLUDE_PATH  =>
         [ [ MAIN => '/usr/local/foo' ],
           [ FOO_WIDGETS => '/usr/local/foo/widgets' ],
           [ BAR => '/usr/local/bar' ],
           [ BAR_WIDGETS => '/usr/local/bar/widgets' ] ],
         };

    Please be aware that you loose compatibility with other
    Catalyst::View::Templated classes if you specify the key names.

INCOMPTIBILITIES
  CHARSET
  The charset of a template no longer defaults to 'utf-8'

  CONFIGURATION
  Automatic post-processing of Mason config variables is not feed back
  into the $self->config hash.

  "use_match" will be silently ignored

  "template_extension" has been deprecated in favor of
  "TEMPLATE_EXTENSION"

  EXCEPTION HANDLING
  A failed request always dies now, instead of returning false with the
  exception in the response body. The error handling is in full
compliance
  with Catalyst::View::Templated now.

SEE ALSO
  Catalyst, HTML::Mason, "Using Mason from a Standalone Script" in
  Catalyst::View::Mason, HTML::Mason::Admin, Catalyst::View::Templated

AUTHOR
  Sebastian Willert <willert at cpan.org>

  Catalyst::View::Mason::Templated is loosely based on
  Catalyst::View::Mason which has been written by the following authors:

  Andres Kievsky "ank at cpan.org", Sebastian Riedel "sri at cpan.org", Marcus
  Ramberg, Florian Ragwitz <rafl at debian.org>

COPYRIGHT
  This program is free software, you can redistribute it and/or modify 
  it under the same terms as Perl itself.