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

[Ash Berlin]

Sebastian Willert wrote:
> 
> 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.
> 

I don't think the end user cares that this module have been
overridden/written. Probably should just me moved to a CONFIG section
and ignore the fact that new does INCLUDE_PATH -> comp_root

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

s/listet/listed/; s/preverably/preferably/;

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

Any reason why you don't put this back in anyway?

Apart from those it seems sane - but I don't know Mason at all if that
matters.