Expand TTSite documentation (RT #33838)

[catagits/Catalyst-View-TT.git] / lib / Catalyst / Helper / View / TTSite.pm

diff --git a/lib/Catalyst/Helper/View/TTSite.pm b/lib/Catalyst/Helper/View/TTSite.pm
index d63ad41..2943d29 100644 (file)
--- a/lib/Catalyst/Helper/View/TTSite.pm
+++ b/lib/Catalyst/Helper/View/TTSite.pm
@@ -12,10 +12,9 @@ sub mk_compclass {
 
 sub mk_templates {
     my ( $self, $helper ) = @_;
-    my $base = $helper->{base};
-    my $tdir = File::Spec->catfile( $base, 'templates' );
-    my $ldir = File::Spec->catfile( $tdir, 'lib' );
-    my $sdir = File::Spec->catfile( $tdir, 'src' );
+    my $base = $helper->{base},;
+    my $ldir = File::Spec->catfile( $base, 'root', 'lib' );
+    my $sdir = File::Spec->catfile( $base, 'root', 'src' );
 
     $helper->mk_dir($ldir);
     $helper->mk_dir($sdir);
@@ -55,18 +54,18 @@ Catalyst::Helper::View::TTSite - Helper for TT view which builds a skeleton web
 # add something like the following to your main application module
 
     sub message : Global {
-        my ($self, $c) = @_;
-        $c->stash->{ template } = 'message.tt2';
-        $c->stash->{ message  } = $c->req->param('message') || 'Hello World';
+        my ( $self, $c ) = @_;
+        $c->stash->{template} = 'message.tt2';
+        $c->stash->{message}  ||= $c->req->param('message') || 'No message';
     }
     
     sub default : Private {
-        my ($self, $c) = @_;
-        $c->stash->{ template } = 'welcome.tt2';
+        my ( $self, $c ) = @_;
+        $c->stash->{template} = 'welcome.tt2';
     }
     
     sub end : Private {
-        my ($self, $c) = @_;
+        my ( $self, $c ) = @_;
         $c->forward('MyApp::V::TT');
     }
 
@@ -76,22 +75,58 @@ This helper module creates a TT View module.  It goes further than
 Catalyst::Helper::View::TT in that it additionally creates a simple
 set of templates to get you started with your web site presentation.
 
-It creates the templates in a F<templates> directory underneath your
+It creates the templates in F<root/> directory underneath your
 main project directory.  In here two further subdirectories are
-created: F<src> which contains the main page templates, and F<lib>
-containing a library of other templates components (header, footer,
+created: F<root/src> which contains the main page templates, and F<root/lib>
+containing a library of other template components (header, footer,
 etc.) that the page templates use.
 
 The view module that the helper creates is automatically configured
 to locate these templates.
 
-=head2 METHODS
+=head2 Default Rendering 
 
-=head3 mk_compclass
+To render a template the following process is applied:
+
+The configuration template F<root/lib/config/main> is rendered. This is
+controlled by the C<PRE_PROCESS> configuration variable set in the controller
+generated by Catalyst::Helper::View::TTsite. Additionally, templates referenced by
+the C<PROCESS> directive will then be rendered. By default the following additional
+templates are set: F<root/lib/config/col>,
+which defines color names and RGB their RGB values and F</root/lib/config/url>,
+which defines site wide variables available to templates.
+
+Next, the template defined by the C<WRAPPER> config variable is called. The default
+wrapper template is located in F<root/lib/site/wrapper>. The wrapper template
+passes files with C<.css/.js/.txt> extensions through as text OR processes
+the templates defined after the C<WRAPPER> directive: C<site/html> and C<site/layout>.
+
+Based on the default value of the C<WRAPPER> directive in F<root/lib/site/wrapper>,
+the following templates are processed in order:
+
+=over 4
+
+=item * F<root/src/your_template.tt2>
+
+=item * F<root/lib/site/footer>
+
+=item * F<root/lib/site/header>
+
+=item * F<root/lib/site/layout>
+
+=item * F<root/lib/site/html>
+
+=back
+
+Finally, the rendered content is returned to the bowser.
+
+=head1 METHODS
+
+=head2 mk_compclass
 
 Generates the component class.
 
-=head3 mk_templates
+=head2 mk_templates
 
 Generates the templates.
 
@@ -122,26 +157,21 @@ package [% class %];
 
 use strict;
 use base 'Catalyst::View::TT';
-use NEXT;
 
-sub new {
-    my $self = shift;
-    my $c    = shift;
-    my $root     = $c->config->{ root };
-    my $template = $c->config->{ template } || { };
-
-    $template->{ CATALYST_VAR } ||= 'Catalyst',
-    $template->{ INCLUDE_PATH } ||= [ "$root/templates/src", "$root/templates/lib" ];
-    $template->{ PRE_PROCESS  } ||= 'config/main';
-    $template->{ WRAPPER      } ||= 'site/wrapper';
-    $template->{ ERROR        } ||= 'error.tt2';
-
-    return $self->NEXT::new($c, @_);
-}
+__PACKAGE__->config({
+    INCLUDE_PATH => [
+        [% app %]->path_to( 'root', 'src' ),
+        [% app %]->path_to( 'root', 'lib' )
+    ],
+    PRE_PROCESS  => 'config/main',
+    WRAPPER      => 'site/wrapper',
+    ERROR        => 'error.tt2',
+    TIMER        => 0
+});
 
 =head1 NAME
 
-[% class %] - TT View Component
+[% class %] - Catalyst TTSite View
 
 =head1 SYNOPSIS
 
@@ -149,7 +179,7 @@ See L<[% app %]>
 
 =head1 DESCRIPTION
 
-TT View Component.
+Catalyst TTSite View.
 
 =head1 AUTHOR
 
@@ -157,8 +187,8 @@ TT View Component.
 
 =head1 LICENSE
 
-This library is free software . You can redistribute it and/or modify
-it under the same terms as perl itself.
+This library is free software, you can redistribute it and/or modify
+it under the same terms as Perl itself.
 
 =cut
 
@@ -218,7 +248,7 @@ __config_col__
       message = site.rgb.green
       error   = site.rgb.red
    };
-%]
+-%]
 __config_url__
 [% TAGS star -%]
 [% base = Catalyst.req.base;
@@ -232,10 +262,10 @@ __config_url__
 __site_wrapper__
 [% TAGS star -%]
 [% IF template.name.match('\.(css|js|txt)');
-     debug("passing page through as text: $template.name");
+     debug("Passing page through as text: $template.name");
      content;
    ELSE;
-     debug("applying HTML page layout wrappers to $template.name\n");
+     debug("Applying HTML page layout wrappers to $template.name\n");
      content WRAPPER site/html + site/layout;
    END;
 -%]