Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

CGI::FormBuilder::Template
Template adapters for FormBuilder

CGI::FormBuilder::Template - Template adapters for FormBuilder


NAME

CGI::FormBuilder::Template - Template adapters for FormBuilder


SYNOPSIS


    # Define a template engine

    package CGI::FormBuilder::Template::Whatever;

    use base 'Whatever::Template::Module';

    sub new {

        my $self  = shift;

        my $class = ref($self) || $self;

        my %opt   = @_;

        # override some options

        $opt{some_setting} = 0;

        $opt{another_var}  = 'Some Value';

        # instantiate the template engine

        $opt{engine} = Whatever::Template::Module->new(%opt);

        return bless \%opt, $class;

    }

    sub render {

        my $self = shift;

        my $form = shift;   # only arg is form object

        # grab any manually-set template params

        my %tmplvar = $form->tmpl_param;

        # example template manipulation

        my $html = $self->{engine}->do_template(%tmplvar);

        return $html;       # scalar HTML is returned

    }


DESCRIPTION

This documentation describes the usage of FormBuilder templates, as well as how to write your own template adapter.

The template engines serve as adapters between CPAN template modules and FormBuilder. A template engine is invoked by using the template option to the top-level new() method:


    my $form = CGI::FormBuilder->new(

                    template => 'filename.tmpl'

               );

This example points to a filename that contains an HTML::Template compatible template to use to layout the HTML. You can also specify the template option as a reference to a hash, allowing you to further customize the template processing options, or use other template engines.

For example, you could turn on caching in HTML::Template with something like the following:


    my $form = CGI::FormBuilder->new(

                    fields => \@fields,

                    template => {

                        filename => 'form.tmpl',

                        shared_cache => 1

                    }

               );

As mentioned, specifying a hashref allows you to use an alternate template processing system like the Template Toolkit. A minimal configuration would look like this:


    my $form = CGI::FormBuilder->new(

                    fields => \@fields,

                    template => {

                        type => 'TT2',      # use Template Toolkit

                        template => 'form.tmpl',

                    },

               );

The type option specifies the name of the engine. Currently accepted types are:


    HTML  -  HTML::Template (default)

    Text  -  Text::Template

    TT2   -  Template Toolkit

    Fast  -  CGI::FastTemplate

In addition to one of these types, you can also specify a complete package name, in which case that module will be autoloaded and its new() and parse() routines used. For example:


    my $form = CGI::FormBuilder->new(

                    fields => \@fields,

                    template => {

                        type => 'My::Template::Module',

                        template => 'form.tmpl',

                    },

               );

All other options besides type are passed to the constructor for that templating system verbatim, so you'll need to consult those docs to see what all the different options do. Skip down to SEE ALSO.


SUBCLASSING TEMPLATE ADAPTERS

In addition to the above included template engines, it is also possible to write your own rendering module. If you come up with something cool, please let the mailing list know!

To do so, you need to write a module which has a sub called render(). This sub will be called by FormBuilder when $form->render is called. This sub can do basically whatever it wants, the only thing it has to do is return a scalar string which is the HTML to print out.

This is actually not hard. Here's a simple adapter which would manipulate an HTML::Template style template:


    # This file is My/HTML/Template.pm

    package My::HTML::Template;

    use CGI::FormBuilder::Template::HTML;

    use base 'CGI::FormBuilder::Template::HTML';

    sub render {

        my $self = shift;    # class object

        my $form = shift;    # $form as only argument

        # the template object (engine) lives here

        my $tmpl = $self->engine;

        # setup vars for our fields (objects)

        for ($form->field) {

            $tmpl->param($_ => $_->value);

        }

        # render output

        my $html = $tmpl->output;

        # return scalar;

        return $html;

    }

    1;  # close module

Then in FormBuilder:


    use CGI::FormBuilder;

    use My::HTML::Template;   # your module

    my $tmpl = My::HTML::Template->new;

    my $form = CGI::FormBuilder->new(

                    fields   => [qw(name email)],

                    header   => 1,

                    template => $tmpl   # pass template object

               );

    # set our company from an extra CGI param

    my $co = $form->cgi_param('company');

    $tmpl->engine->param(company => $co);

    # and render like normal

    print $form->render;

That's it! For more details, the best thing to do is look through the guts of one of the existing template engines and go from there.


SEE ALSO

the CGI::FormBuilder manpage, the CGI::FormBuilder::Template::HTML manpage, the CGI::FormBuilder::Template::Text manpage, the CGI::FormBuilder::Template::TT2 manpage, the CGI::FormBuilder::Template::Fast manpage


REVISION

$Id: Template.pm,v 1.15 2005/03/11 19:39:56 nwiger Exp $


AUTHOR

Copyright (c) 2000-2005 Nathan Wiger <nate@sun.com>. All Rights Reserved.

This module is free software; you may copy this under the terms of the GNU General Public License, or the Artistic License, copies of which should have accompanied your Perl kit.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy