NAME

CGI::Builder::HTMLtmpl - CGI::Builder and HTML::Template integration

VERSION 1.21

To have the complete list of all the extensions of the CBF, see "Extensions List" in CGI::Builder

INSTALLATION

Prerequisites

    CGI::Builder    >= 1.0
    HTML::Template  >= 2.6

CPAN

    perl -MCPAN -e 'install CGI::Builder::HTMLtmpl'

You have also the possibility to use the Bundle to install all the extensions and prerequisites of the CBF in just one step. Please, notice that the Bundle will install A LOT of modules that you might not need, so use it specially if you want to extensively try the CBF.

    perl -MCPAN -e 'install Bundle::CGI::Builder::Complete'

Standard installation

From the directory where this file is located, type:

    perl Makefile.PL
    make
    make test
    make install

SYNOPSIS

    use CGI::Builder
    qw| CGI::Builder::HTMLtmpl
        ...
      |;

DESCRIPTION

Note: You should know CGI::Builder.

This module transparently integrates CGI::Builder and HTML::Template in a very handy and flexible framework that can save you some coding. It provides you a mostly automatic template system based on HTML::Template: usually you will have just to supply the run time values to the object and this extension will manage automatically all the other tasks of the page production process (such as generating the output and setting the page_content property).

Note: With this extension you don't need to explicitly set the page_content to the output of your template object (ht->output()) in your Page Handlers, because it will be automatically set. You should explicitly set the page_content property just in case you want to bypass the template system:

    # in order to produce the output with the template 'myPage.tmpl',
    # usually you just need to pass the param to the object
    sub PH_myPage {
        my $s = shift;
        $s->ht_param( something => 'something' );
    }
    
    # but if you want to completely bypass the template system
    # just set the page_content
    sub PH_myPage {
        my $s = shift;
        $s->page_content = 'some content';
    }

Note: This extension is not as magic and memory saving as the CGI::Builder::Magic template extension, because HTML::Template requires a specific input data structure (i.e. does not allow call back subs unless you use the HTML::Template::Expr), and does not allow to print the output during the process. On the other hand it should be a few milliseconds faster than CGI::Builder::Magic in producing the output.

EXAMPLES

Simple CBB (all defaults)

This is a complete CBB that uses all the default to load the './tm/index.tmpl'template and fill it with a couple of run time values and automatically send the page_content to the client.

    package My::WebApp
    use CGI::Builder
    qw| CGI::Builder::HTMLtmpl
      |;
      
    sub PH_index {
        my $s = shift;
        $s->ht_param( myVar      => 'my Variable',
                      myOtherVar => 'other Variable');
    }
    
    1;

More complex CBB (overriding defaults)

This is a more complex complete CBB that will automatically send the page_content to the client:

    package My::WebApp
    use CGI::Builder
    qw| CGI::Builder::HTMLtmpl
      |;
    
    # this will init some properties overriding the default
    # and adding some option to the ht creation
    sub OH_init {
        my $s = shift;
        $s->page_suffix = '.html';               # override defaults
        $s->ht_new_args( path => ['/my/path'],   # override defaults
                         die_on_bad_params => 0,
                         cache => 1 );
    }
    
    # this will be called for page 'index' or if no page is specified
    # it will load the '/my/path/index.html' file (since page_suffix is '.html')
    # and will fill it with the following variables and send the output()
    sub PH_index {
        my $s = shift;
        $s->ht_param( myVar      => 'my Variable',
                      myOtherVar => 'other Variable');
    }
    
    # this will override the default template for this handler
    # (i.e. '/my/path/specialPage.html') so loading '/my/path/special.tmp'
    # template, filling and sending the output as usual
    sub PH_specialPage {
        my $s = shift;
        $s->ht_new_args( filename => 'special.tmp')     # override defaults
        $s->ht_param( mySomething => 'something' );
    }
    
    1;

PROPERTY and GROUP ACCESSORS

This module adds some template properties (all those prefixed with 'ht_') to the standard CBF properties. The default of these properties are usually smart enough to do the right job for you, but you can fine-tune the behaviour of your CBB by setting them to the value you need.

ht_new_args( arguments )

This property group accessor handles the HTML::Template constructor arguments that are used in the creation of the internal HTML::Template object. Use it to change or add the argument you need to the creation of the new object.

It uses the following defaults:

• filename

  This option is set to the page_name value plus the page_suffix value.

      filename => $s->page_name.$s->page_suffix
      
      # when the page_name is 'myPage'
      # and the page_suffix is the default '.tmpl'
      # it will be expanded to;
      filename => 'myPage.tmpl'

• path

  This option is set to the page_path value.

     path => [ $s->page_path ]

You should use ht_new_args at the very beginning of the process, for any argument but 'filename'.

    # set args in the new instance statement
    my $webapp = My::WebApp
                ->new( ht_new_args => { path => ['/my/path'],  # override defaults
                                        die_on_bad_params => 0,
                                        cache => 1
                                      }
                       .....
                     );
                                 
    # or in the OH_init handler
    sub OH_init {
        my $s = shift;
        $s->ht_new_args( path => ['/my/path'],   # override defaults
                         die_on_bad_params => 0,
                         cache => 1 );
    }

Note about custom filenames: it is preferable to avoid to explicitly set the filename argument and let the default do it for you. Anyway if you still need to set the filename, you must know that you have to reset it if you switch_to() another page AFTER setting it.

    # and/or in a Page Handler
    sub PH_specialPage {
        my $s = shift;
        $s->ht_new_args( filename => 'special.tmp')     # override defaults
        $s->ht_param( mySomething => 'something' );
    }

Note: You can completely override the creation of the internal object by overriding the ht_new() method.

ht_param

This property group accessor handles the HTML::Template parameters that are internally passed to the ht object before the output production. Use it to collect the params that will be passed to the object.

Note: This group accessor has been added in the 1.21 version in order to avoid to use the ht property:

   # deprecated
   $s->ht->param(...)
   # OK
   $s->ht_param(...)

ht

This property is used internally, so you usually don't need to use it directly in your code. In the rare case you need to use it (e.g. if you need to use HTML::Template::query() method), you should use it after any other switch_to() calls, or you should explicitly undef it just before the switch_to() call.

Note: You can change the default arguments that are internally used to create the object by using the ht_new_args group accessor, or you can completely override the creation of the internal object by overriding the ht_new() method.

Advanced Note: Unlike other template object, the HTML::Template object needs to know the filename at the moment of its creation. That restriction considerably limits the possibility to switch_to another page if and when the ht property has been already used (i.e. the HTML::Template object has been already created). For this reason, the ht property is preferably used only as an ending point (i.e. after we know what is the ultimate page to serve).

CBF changed property defaults

CBF page_suffix

This module sets the default of the page_suffix to the traditional '.tmpl'. You can override it by just setting another suffix of your choice.

CBF page_content

This module sets the default of the page_content to the template output produced by using the internal ht->output(). If you want to bypass the template system in any Page Handler, just explicitly set the page_content to the content you want to send.

METHODS

ht_new()

This method is not intended to be used directly in your CBB. It is used internally to initialize and returns the HTML::Template object, but you need to know how it does its job. If you need some more customization you can redefine the method in your CBB.

switch_to overriding

If (and only if) your application has to switch_to after using the ht property quite often, it may be handy to implement the following switch_to() in your own CBB:

  sub switch_to {
      my $s = shift;
      $s->ht_new_args( {filename => $_[0].$s->page_suffix} )
          if $s{ht_new_args}{filename};
      $s->ht = undef;
      $s->CGI::Builder::switch_to(@_);
  }

CBF overridden methods

page_content_check

This extension use this method to check if the template file exists before using its template print method, thus avoiding a fatal error when the requested page is not found.

Note: You don't need to directly use this method since it's internally called at the very start of the RESPONSE phase. You don't need to override it if you want just to send a different header status, since the CBF sets the status just if it is not defined yet.

AVOIDING MISTAKES

• Don't use the ht_new_args in all the Page Handlers: it is intended to be used once e.g. in an OH_init OR as an exceptional case in any Page Handler just to allow overriding (e.g. a different filename just for that particular Page Handler).

• Don't explicitly set the page_content property unless you want to bypass the template system: this extension set it for you.

SUPPORT

See "SUPPORT" in CGI::Builder.

AUTHOR and COPYRIGHT

© 2004 by Domizio Demichelis (http://perl.4pro.net)

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

CREDITS

Thanks to Rob Arnold for his testing and suggestions.

cpanm CGI::Builder::HTMLtmpl

perl -MCPAN -e shell
install CGI::Builder::HTMLtmpl