view release on metacpan or  search on metacpan

lib/Catalyst/Helper/View/TT/Bootstrap/YUI/Manual.pm  view on Meta::CPAN

Catalyst::Helper::View::TT::Bootstrap::Manual - User guide and reference for
files generated by Catalyst::Helper::View::TT::Bootstrap::YUI.

=head1 SYNOPSIS

This is a replacement for Catalyst::View::TT, which operates in the same
fashion.  To create all the necessary files, simply run:

 script/myapp_create.pl view TT TT::Bootstrap::YUI

This will generate the entire bootstrapped site structure.  Read on for details.

=head1 DESCRIPTION

=head2 Files and Directory

The files and directories generated under your application root 
(e.g. MyApp/) are:

    lib/MyApp/View/TT.pm # The TT View module with a couple extras

    root/
        site/
            wrapper.tt         # routes all pages to their appropriate layout
            html.tt            # renders the html wrapper.  See below

            header/            # directory for header templates
                default.tt     # placeholder masthead for you to override

            footer/            # directory for footer templates
                default.tt     # placeholder footer for you to override

            nav/               # directory for navigation templates. See below
                default.tt     # placeholder nav for you to override

            layout/            # directory for various content layouts
                default.tt     # basic layout, renders content only

            shared/            # directory for templates shared by several pages
                base.tt        # core macros and stash framework.  See below

        static/                # directory root of static resources
            images/            # content images go here or in a subdir
            scripts/           # javascript files go here or in a subdir
            css/               # stylesheets go here or in a subdir
                screen.css     # global stylesheet supporting the provided
                               # layouts and resetting default browser styles
                images/        # css images go here on in a subdir

=head2 View Module Configuration

The generated View sets the following configuration key/values:

 PRE_PROCESS        => 'site/shared/base.tt',
 WRAPPER            => 'site/wrapper.tt',
 TEMPLATE_EXTENSION => '.tt',
 TIMER              => 0,
 static_root        => '/static',
 static_build       => 0,
 default_tz         => 'America/Los_Angeles',
 default_locale     => 'en_US',
 formats => {
    # All date formats to define:
    date => {
        'date'  => '%D',
        'short' => '%b %e, %G',
        'long'  => '%F %l:%M %p'
    }
 }

=head3 Formatting and Dynamic Filters

The generated View.pm class defines filters for (at the moment) doing DateTime
formatting, complete with locale and timezone settings.

Either a DateTime object or a string that can be parsed as a Date/Time can be
passed in to the filters:

    [% dt_object | date_long %]

This will set the timezone, and then format according to the configuration.

If you just have a string, it is useful for doing standard date formatting
in your application:

    [% '2009-01-01T03:13:56' | date_long %]

The name of the filter is "date_$configkey", so if you wanted to have a format
called "_for_americans" you could add this configuration:

 date => {
    'for_americans' => '%m/%d/%y'
 }

This would create the usable filter "date_for_americans".

=head3 static_build and static_root

These options are unique to the ::Bootstrap package, and give
you a managed static path to reference, as well as a "static" macro.

 <p>The current static root is [% static_root %]</p>
 <p>And the current static build is [% static_build %]</p>

=over 4

=item static_root

Used by the macro 'static' (see below) to locate static resources such as
images, stylesheets, and javascript files.  The default value is '/static'
(served from MyApp/root/static).

=item static_build

(Optional) Used by the macro 'static' to append the returned URIs with a query
string 'ver' with the value assigned to static_build.  This is particularly
useful to ensure returning site visitors get the latest version of static
resources, and not served from the browser cache. By default, this is set to 0
(versioning off).

Two strategies for use are

=over 4

=item 1

Manually update it when a static file is modifed, using the a datestamp value.
Using a YAML config makes this more convenient.

    ...
    View::TT:
        static_build: 20070907
    ...