[catagits/Catalyst-View-TT.git] / README

NAME
    Catalyst::View::TT - Template View Class

SYNOPSIS
    # use the helper to create View myapp_create.pl view TT TT

    # configure in lib/MyApp.pm

        MyApp->config({
            name     => 'MyApp',
            root     => MyApp->path_to('root');,
            'V::TT' => {
                # any TT configurations items go here
                INCLUDE_PATH => [
                  MyApp->path_to( 'root', 'src' ), 
                  MyApp->path_to( 'root', 'lib' ), 
                ],
                PRE_PROCESS        => 'config/main',
                WRAPPER            => 'site/wrapper',
                TEMPLATE_EXTENSION => '.tt',

                # two optional config items
                CATALYST_VAR => 'Catalyst',
                TIMER        => 1,
            },
        });
         
    # render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm

        sub message : Global {
            my ( $self, $c ) = @_;
            $c->stash->{template} = 'message.tt2';
            $c->stash->{message}  = 'Hello World!';
            $c->forward('MyApp::V::TT');
        }

    # access variables from template

        The message is: [% message %].
    
        # example when CATALYST_VAR is set to 'Catalyst'
        Context is [% Catalyst %]          
        The base is [% Catalyst.req.base %] 
        The name is [% Catalyst.config.name %] 
    
        # example when CATALYST_VAR isn't set
        Context is [% c %]
        The base is [% base %]
        The name is [% name %]

DESCRIPTION
    This is the Catalyst view class for the Template Toolkit. Your
    application should defined a view class which is a subclass of this
    module. The easiest way to achieve this is using the myapp_create.pl
    script (where myapp should be replaced with whatever your application is
    called). This script is created as part of the Catalyst setup.

        $ script/myapp_create.pl view TT TT

    This creates a MyApp::V::TT.pm module in the lib directory (again,
    replacing "MyApp" with the name of your application) which looks
    something like this:

        package FooBar::V::TT;
    
        use strict;
         use base 'Catalyst::View::TT';

        __PACKAGE__->config->{DEBUG} = 'all';

    Now you can modify your action handlers in the main application and/or
    controllers to forward to your view class. You might choose to do this
    in the end() method, for example, to automatically forward all actions
    to the TT view class.

        # In MyApp or MyApp::Controller::SomeController
    
        sub end : Private {
            my( $self, $c ) = @_;
            $c->forward('MyApp::V::TT');
        }

  CONFIGURATION
    There are a three different ways to configure your view class. The first
    way is to call the "config()" method in the view subclass. This happens
    when the module is first loaded.

        package MyApp::V::TT;
    
        use strict;
        use base 'Catalyst::View::TT';

        MyApp::V::TT->config({
            INCLUDE_PATH => [
                MyApp->path_to( 'root', 'templates', 'lib' ),
                MyApp->path_to( 'root', 'templates', 'src' ),
            ],
            PRE_PROCESS  => 'config/main',
            WRAPPER      => 'site/wrapper',
        });

    The second way is to define a "new()" method in your view subclass. This
    performs the configuration when the view object is created, shortly
    after being loaded. Remember to delegate to the base class "new()"
    method (via "$self->NEXT::new()" in the example below) after performing
    any configuration.

        sub new {
            my $self = shift;
            $self->config({
                INCLUDE_PATH => [
                    MyApp->path_to( 'root', 'templates', 'lib' ),
                    MyApp->path_to( 'root', 'templates', 'src' ),
                ],
                PRE_PROCESS  => 'config/main',
                WRAPPER      => 'site/wrapper',
            });
            return $self->NEXT::new(@_);
        }
 
    The final, and perhaps most direct way, is to define a class item in
    your main application configuration, again by calling the uniquitous
    "config()" method. The items in the class hash are added to those
    already defined by the above two methods. This happens in the base class
    new() method (which is one reason why you must remember to call it via
    "NEXT" if you redefine the "new()" method in a subclass).

        package MyApp;
    
        use strict;
        use Catalyst;
    
        MyApp->config({
            name     => 'MyApp',
            root     => MyApp->path_to('root'),
            'V::TT' => {
                INCLUDE_PATH => [
                    MyApp->path_to( 'root', 'templates', 'lib' ),
                    MyApp->path_to( 'root', 'templates', 'src' ),
                ],
                PRE_PROCESS  => 'config/main',
                WRAPPER      => 'site/wrapper',
            },
        });

    Note that any configuration items defined by one of the earlier methods
    will be overwritten by items of the same name provided by the latter
    methods.

  DYNAMIC INCLUDE_PATH
    It is sometimes needed to dynamically add additional paths to the
    INCLUDE_PATH variable of the template object. This can be done by
    setting 'additional_include_paths' on stash to a referrence to an array
    with additional paths:

        $c->stash->{additional_template_paths} = [$c->config->{root} . '/test_include_path']; 

  RENDERING VIEWS
    The view plugin renders the template specified in the "template" item in
    the stash.

        sub message : Global {
            my ( $self, $c ) = @_;
            $c->stash->{template} = 'message.tt2';
            $c->forward('MyApp::V::TT');
        }

    If a class item isn't defined, then it instead uses the current match,
    as returned by "$c->match". In the above example, this would be
    "message".

    The items defined in the stash are passed to the Template Toolkit for
    use as template variables.

    sub message : Global { sub default : Private { my ( $self, $c ) = @_;
    $c->stash->{template} = 'message.tt2'; $c->stash->{message} = 'Hello
    World!'; $c->forward('MyApp::V::TT'); }

    A number of other template variables are also added:

        c      A reference to the context object, $c
        base   The URL base, from $c->req->base()
        name   The application name, from $c->config->{ name }

    These can be accessed from the template in the usual way:

    <message.tt2>:

        The message is: [% message %]
        The base is [% base %]
        The name is [% name %]

    The output generated by the template is stored in
    "$c->response->output".

  TEMPLATE PROFILING
  METHODS
    new The constructor for the TT view. Sets up the template provider, and
        reads the application config.

    process
        Renders the template specified in "$c->stash->{template}" or
        "$c->request->match". Template variables are set up from the
        contents of "$c->stash", augmented with "base" set to
        "$c->req->base", "c" to $c and "name" to "$c->config->{name}".
        Alternately, the "CATALYST_VAR" configuration item can be defined to
        specify the name of a template variable through which the context
        reference ($c) can be accessed. In this case, the "c", "base" and
        "name" variables are omitted. Output is stored in
        "$c->response->output".

    config
        This method allows your view subclass to pass additional settings to
        the TT configuration hash, or to set the options as below:

        "CATALYST_VAR"
          Allows you to change the name of the Catalyst context object. If
          set, it will also remove the base and name aliases, so you will
          have access them through <context>.

          For example:

              MyApp->config({
                  name     => 'MyApp',
                  root     => MyApp->path_to('root'),
                  'V::TT' => {
                      CATALYST_VAR => 'Catalyst',
                  },
              });

          message.tt2:

              The base is [% Catalyst.req.base %]
              The name is [% Catalyst.config.name %]

        "TIMER"
          If you have configured Catalyst for debug output, and turned on
          the TIMER setting, "Catalyst::View::TT" will enable profiling of
          template processing (using Template::Timer). This will embed HTML
          comments in the output from your templates, such as:

              <!-- TIMER START: process mainmenu/mainmenu.ttml -->
              <!-- TIMER START: include mainmenu/cssindex.tt -->
              <!-- TIMER START: process mainmenu/cssindex.tt -->
              <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
              <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->

              ....

              <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->

        "TEMPLATE_EXTENSION"
          a sufix to add when looking for templates bases on the "match"
          method in Catalyst::Request.

          For example:

            package MyApp::C::Test;
            sub test : Local { .. } 

          Would by default look for a template in <root>/test/test. If you
          set TEMPLATE_EXTENSION to '.tt', it will look for
          <root>/test/test.tt.

  HELPERS
    The Catalyst::Helper::View::TT and Catalyst::Helper::View::TTSite helper
    modules are provided to create your view module. There are invoked by
    the myapp_create.pl script:

        $ script/myapp_create.pl view TT TT

        $ script/myapp_create.pl view TT TTSite

    The Catalyst::Helper::View::TT module creates a basic TT view module.
    The Catalyst::Helper::View::TTSite module goes a little further. It also
    creates a default set of templates to get you started. It also
    configures the view module to locate the templates automatically.

SEE ALSO
    Catalyst, Catalyst::Helper::View::TT, Catalyst::Helper::View::TTSite,
    Template::Manual

AUTHORS
    Sebastian Riedel, "sri@cpan.org"

    Marcus Ramberg, "mramberg@cpan.org"

    Jesse Sheidlower, "jester@panix.com"

    Andy Wardley, "abw@cpan.org"

COPYRIGHT
    This program is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.
Commit	Line	Data
8077080c	1	NAME
	2	Catalyst::View::TT - Template View Class
	3
	4	SYNOPSIS
c0eb0527	5	# use the helper to create View myapp_create.pl view TT TT
8077080c	6
c0eb0527	7	# configure in lib/MyApp.pm
8077080c	8
c0eb0527	9	MyApp->config({
c0eb0527	10	name => 'MyApp',
3cf1e0a6	11	root => MyApp->path_to('root');,
3cf1e0a6	12	'V::TT' => {
c0eb0527	13	# any TT configurations items go here
c0eb0527	14	INCLUDE_PATH => [
3cf1e0a6	15	MyApp->path_to( 'root', 'src' ),
3cf1e0a6	16	MyApp->path_to( 'root', 'lib' ),
c0eb0527	17	],
3cf1e0a6	18	PRE_PROCESS => 'config/main',
	19	WRAPPER => 'site/wrapper',
	20	TEMPLATE_EXTENSION => '.tt',
c0eb0527	21
	22	# two optional config items
	23	CATALYST_VAR => 'Catalyst',
	24	TIMER => 1,
	25	},
	26	});
	27
	28	# render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
	29
	30	sub message : Global {
	31	my ( $self, $c ) = @_;
	32	$c->stash->{template} = 'message.tt2';
	33	$c->stash->{message} = 'Hello World!';
	34	$c->forward('MyApp::V::TT');
	35	}
8077080c	36
c0eb0527	37	# access variables from template
	38
	39	The message is: [% message %].
	40
	41	# example when CATALYST_VAR is set to 'Catalyst'
	42	Context is [% Catalyst %]
	43	The base is [% Catalyst.req.base %]
	44	The name is [% Catalyst.config.name %]
8077080c	45
c0eb0527	46	# example when CATALYST_VAR isn't set
	47	Context is [% c %]
	48	The base is [% base %]
	49	The name is [% name %]
8077080c	50
8077080c	51	DESCRIPTION
c0eb0527	52	This is the Catalyst view class for the Template Toolkit. Your
	53	application should defined a view class which is a subclass of this
	54	module. The easiest way to achieve this is using the myapp_create.pl
	55	script (where myapp should be replaced with whatever your application is
	56	called). This script is created as part of the Catalyst setup.
	57
	58	$ script/myapp_create.pl view TT TT
	59
	60	This creates a MyApp::V::TT.pm module in the lib directory (again,
	61	replacing "MyApp" with the name of your application) which looks
	62	something like this:
	63
	64	package FooBar::V::TT;
	65
	66	use strict;
	67	use base 'Catalyst::View::TT';
	68
	69	__PACKAGE__->config->{DEBUG} = 'all';
	70
	71	Now you can modify your action handlers in the main application and/or
	72	controllers to forward to your view class. You might choose to do this
	73	in the end() method, for example, to automatically forward all actions
	74	to the TT view class.
	75
	76	# In MyApp or MyApp::Controller::SomeController
	77
	78	sub end : Private {
	79	my( $self, $c ) = @_;
	80	$c->forward('MyApp::V::TT');
	81	}
	82
	83	CONFIGURATION
	84	There are a three different ways to configure your view class. The first
	85	way is to call the "config()" method in the view subclass. This happens
	86	when the module is first loaded.
	87
	88	package MyApp::V::TT;
	89
	90	use strict;
	91	use base 'Catalyst::View::TT';
	92
c0eb0527	93	MyApp::V::TT->config({
3cf1e0a6	94	INCLUDE_PATH => [
	95	MyApp->path_to( 'root', 'templates', 'lib' ),
	96	MyApp->path_to( 'root', 'templates', 'src' ),
	97	],
c0eb0527	98	PRE_PROCESS => 'config/main',
	99	WRAPPER => 'site/wrapper',
	100	});
	101
	102	The second way is to define a "new()" method in your view subclass. This
	103	performs the configuration when the view object is created, shortly
	104	after being loaded. Remember to delegate to the base class "new()"
	105	method (via "$self->NEXT::new()" in the example below) after performing
	106	any configuration.
	107
	108	sub new {
	109	my $self = shift;
	110	$self->config({
3cf1e0a6	111	INCLUDE_PATH => [
	112	MyApp->path_to( 'root', 'templates', 'lib' ),
	113	MyApp->path_to( 'root', 'templates', 'src' ),
	114	],
c0eb0527	115	PRE_PROCESS => 'config/main',
	116	WRAPPER => 'site/wrapper',
	117	});
	118	return $self->NEXT::new(@_);
	119	}
	120
	121	The final, and perhaps most direct way, is to define a class item in
	122	your main application configuration, again by calling the uniquitous
	123	"config()" method. The items in the class hash are added to those
	124	already defined by the above two methods. This happens in the base class
	125	new() method (which is one reason why you must remember to call it via
	126	"NEXT" if you redefine the "new()" method in a subclass).
	127
	128	package MyApp;
	129
	130	use strict;
	131	use Catalyst;
	132
c0eb0527	133	MyApp->config({
c0eb0527	134	name => 'MyApp',
3cf1e0a6	135	root => MyApp->path_to('root'),
	136	'V::TT' => {
	137	INCLUDE_PATH => [
	138	MyApp->path_to( 'root', 'templates', 'lib' ),
	139	MyApp->path_to( 'root', 'templates', 'src' ),
	140	],
c0eb0527	141	PRE_PROCESS => 'config/main',
	142	WRAPPER => 'site/wrapper',
	143	},
	144	});
	145
	146	Note that any configuration items defined by one of the earlier methods
	147	will be overwritten by items of the same name provided by the latter
	148	methods.
	149
3cf1e0a6	150	DYNAMIC INCLUDE_PATH
	151	It is sometimes needed to dynamically add additional paths to the
	152	INCLUDE_PATH variable of the template object. This can be done by
	153	setting 'additional_include_paths' on stash to a referrence to an array
	154	with additional paths:
	155
	156	$c->stash->{additional_template_paths} = [$c->config->{root} . '/test_include_path'];
	157
c0eb0527	158	RENDERING VIEWS
	159	The view plugin renders the template specified in the "template" item in
	160	the stash.
	161
	162	sub message : Global {
	163	my ( $self, $c ) = @_;
	164	$c->stash->{template} = 'message.tt2';
	165	$c->forward('MyApp::V::TT');
	166	}
	167
	168	If a class item isn't defined, then it instead uses the current match,
	169	as returned by "$c->match". In the above example, this would be
	170	"message".
	171
	172	The items defined in the stash are passed to the Template Toolkit for
	173	use as template variables.
	174
	175	sub message : Global { sub default : Private { my ( $self, $c ) = @_;
	176	$c->stash->{template} = 'message.tt2'; $c->stash->{message} = 'Hello
	177	World!'; $c->forward('MyApp::V::TT'); }
	178
	179	A number of other template variables are also added:
	180
	181	c A reference to the context object, $c
	182	base The URL base, from $c->req->base()
	183	name The application name, from $c->config->{ name }
	184
	185	These can be accessed from the template in the usual way:
	186
	187	<message.tt2>:
	188
	189	The message is: [% message %]
	190	The base is [% base %]
	191	The name is [% name %]
2599ee6f	192
c0eb0527	193	The output generated by the template is stored in
	194	"$c->response->output".
	195
	196	TEMPLATE PROFILING
caa61517	197	METHODS
c0eb0527	198	new The constructor for the TT view. Sets up the template provider, and
	199	reads the application config.
	200
	201	process
	202	Renders the template specified in "$c->stash->{template}" or
	203	"$c->request->match". Template variables are set up from the
	204	contents of "$c->stash", augmented with "base" set to
	205	"$c->req->base", "c" to $c and "name" to "$c->config->{name}".
	206	Alternately, the "CATALYST_VAR" configuration item can be defined to
	207	specify the name of a template variable through which the context
	208	reference ($c) can be accessed. In this case, the "c", "base" and
	209	"name" variables are omitted. Output is stored in
	210	"$c->response->output".
	211
	212	config
	213	This method allows your view subclass to pass additional settings to
3cf1e0a6	214	the TT configuration hash, or to set the options as below:
	215
	216	"CATALYST_VAR"
	217	Allows you to change the name of the Catalyst context object. If
	218	set, it will also remove the base and name aliases, so you will
	219	have access them through <context>.
	220
	221	For example:
	222
	223	MyApp->config({
	224	name => 'MyApp',
	225	root => MyApp->path_to('root'),
	226	'V::TT' => {
	227	CATALYST_VAR => 'Catalyst',
	228	},
	229	});
	230
	231	message.tt2:
	232
	233	The base is [% Catalyst.req.base %]
	234	The name is [% Catalyst.config.name %]
	235
	236	"TIMER"
	237	If you have configured Catalyst for debug output, and turned on
	238	the TIMER setting, "Catalyst::View::TT" will enable profiling of
	239	template processing (using Template::Timer). This will embed HTML
	240	comments in the output from your templates, such as:
	241
	242	<!-- TIMER START: process mainmenu/mainmenu.ttml -->
	243	<!-- TIMER START: include mainmenu/cssindex.tt -->
	244	<!-- TIMER START: process mainmenu/cssindex.tt -->
	245	<!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
	246	<!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
	247
	248	....
	249
	250	<!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
	251
	252	"TEMPLATE_EXTENSION"
	253	a sufix to add when looking for templates bases on the "match"
	254	method in Catalyst::Request.
	255
	256	For example:
	257
	258	package MyApp::C::Test;
	259	sub test : Local { .. }
	260
	261	Would by default look for a template in <root>/test/test. If you
	262	set TEMPLATE_EXTENSION to '.tt', it will look for
	263	<root>/test/test.tt.
8077080c	264
c0eb0527	265	HELPERS
	266	The Catalyst::Helper::View::TT and Catalyst::Helper::View::TTSite helper
	267	modules are provided to create your view module. There are invoked by
	268	the myapp_create.pl script:
	269
	270	$ script/myapp_create.pl view TT TT
	271
	272	$ script/myapp_create.pl view TT TTSite
	273
	274	The Catalyst::Helper::View::TT module creates a basic TT view module.
	275	The Catalyst::Helper::View::TTSite module goes a little further. It also
	276	creates a default set of templates to get you started. It also
	277	configures the view module to locate the templates automatically.
8077080c	278
8077080c	279	SEE ALSO
c0eb0527	280	Catalyst, Catalyst::Helper::View::TT, Catalyst::Helper::View::TTSite,
	281	Template::Manual
	282
	283	AUTHORS
	284	Sebastian Riedel, "sri@cpan.org"
	285
	286	Marcus Ramberg, "mramberg@cpan.org"
	287
	288	Jesse Sheidlower, "jester@panix.com"
8077080c	289
c0eb0527	290	Andy Wardley, "abw@cpan.org"
8077080c	291
	292	COPYRIGHT
	293	This program is free software, you can redistribute it and/or modify it
	294	under the same terms as Perl itself.
	295