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::Text
FormBuilder interface to Text::Template

CGI::FormBuilder::Template::Text - FormBuilder interface to Text::Template


NAME

CGI::FormBuilder::Template::Text - FormBuilder interface to Text::Template


SYNOPSIS


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

                    fields   => \@fields,

                    template => {

                        type => 'Text',

                        template => 'form.tmpl',

                        variable => 'form',

                    }

               );


DESCRIPTION

This engine adapts FormBuilder to use Text::Template. Usage is very similar to Template Toolkit:


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

                    fields => \@fields,

                    template => {

                        type => 'Text',           # use Text::Template

                        template => 'form.tmpl',

                    }

               );

The default options passed into Text::Template->new() with this calling form are:


    TYPE   => 'FILE'

    SOURCE => 'form.tmpl'

    DELIMITERS => ['<%','%>']

As these params are passed for you, your template will look very similar to ones used by Template Toolkit and HTML::Mason (the Text::Template default delimiters are { and }, but using alternative delimiters speeds it up by about 25%, and the <% and %> delimiters are good, familiar-looking alternatives).


    <% $jshead %>  -  JavaScript to stick in <head>

    <% $title  %>  -  The <title> of the HTML form

    <% $start  %>  -  Opening <form> tag and internal fields

    <% $submit %>  -  The submit button(s)

    <% $reset  %>  -  The reset button

    <% $end    %>  -  Closing </form> tag

    <% $fields %>  -  List of fields

    <% $field  %>  -  Hash of fields (for lookup by name)

Note that you refer to variables with a preceding $, just like in Perl. Like Template Toolkit, you can specify a variable to place fields under:


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

        fields => \@fields,

        template => {

             type => 'Text',

             template => 'form.tmpl',

             variable => 'form'

        },

    );

Unlike Template Toolkit, though, these will not be placed in OO-style, dot-separated vars. Instead, a hash will be created which you then reference:


    <% $form{jshead} %>

    <% $form{start}  %>

    etc.

And field data is in a hash-of-hashrefs format:


    For a field named...  The field data is in...

    --------------------  -----------------------

    job                   <% $form{field}{job}   %]

    size                  <% $form{field}{size}  %]

    email                 <% $form{field}{email} %]

Since Text::Template looks so much like Perl, you can access individual elements and create variables like so:


    <%

        my $myfield = $form{field}{email};

        $myfield->{label};      # text label

        $myfield->{field};      # field input tag

        $myfield->{value};      # first value

        $myfield->{values};     # list of all values

        $myfield->{options};    # list of all options

        $myfield->{required};   # required flag

        $myfield->{invalid};    # invalid flag

        $myfield->{error};      # error string if invalid

    %>

    <%

        for my $field (@{$form{fields}}) {

            $OUT .= "<tr>\n<td>" . $field->{label} . "</td> <td>" 

                                 . $field->{field} . "</td>\n<tr>";

        }

    %>

In addition, when using the engine option, you supply an existing Text::Template object or a hash of parameters to be passed to new(). For example, you can ask for different delimiters yourself:


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

        fields => \@fields,

        template => {

             type => 'Text',

             template => 'form.tmpl',

             variable => 'form',

             engine   => {

                DELIMITERS => [ '[@--', '--@]' ],

             },

             data => {

                  version => 1.23,

                  author  => 'Fred Smith',

             },

        },

    );

If you pass a hash of parameters, you can override the TYPE and SOURCE parameters, as well as any other Text::Template options. For example, you can pass in a string template with TYPE => STRING instead of loading it from a file. You must specify both TYPE and SOURCE if doing so. The good news is this is trivial:


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

        fields => \@fields,

        template => {

             type => 'Text',

             variable => 'form',

             engine   => {

                  TYPE => 'STRING',

                  SOURCE => $string,

                  DELIMITERS => [ '[@--', '--@]' ],

             },

             data => {

                  version => 1.23,

                  author  => 'Fred Smith',

             },

        },

    );

If you get the crazy idea to let users of your application pick the template file (strongly discouraged) and you're getting errors, look at the Text::Template documentation for the UNTAINT feature.

Also, note that Text::Template's PREPEND => 'use strict;' option is not recommended due to the dynamic nature for FormBuilder. If you use it, then you'll have to declare each variable that FormBuilder puts into your template with use vars qw($jshead' ... etc);

If you're really stuck on this, though, a workaround is to say:


    PREPEND => 'use strict; use vars qw(%form);'

and then set the option variable => 'form'. That way you can have strict Perl without too much hassle, except that your code might be exhausting to look at :-). Things like $form{field}{your_field_name}{field} end up being all over the place, instead of the nicer short forms.

Finally, when you use the data template option, the keys you specify will be available to the template as regular variables. In the above example, these would be <% $version %> and <% $author %>. And complex datatypes are easy:


    data => {

            anArray => [ 1, 2, 3 ],

            aHash => { orange => 'tangy', chocolate => 'sweet' },

    }

This becomes the following in your template:


    <%

        @anArray;    # you can use $myArray[1] etc.

        %aHash;      # you can use $myHash{chocolate} etc.

    %>

For more information, please consult the Text::Template documentation.


SEE ALSO

the CGI::FormBuilder manpage, the CGI::FormBuilder::Template manpage, the Text::Template manpage


REVISION

$Id: Text.pm,v 1.17 2005/03/14 19:31:56 nwiger Exp $


AUTHOR

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

Text::Template support is due to huge contributions by Jonathan Buhacoff. Thanks man.

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