CGI::FormBuilder::Template::Fast - FormBuilder interface to CGI::FastTemplate

CGI-FormBuilder documentation Contained in the CGI-FormBuilder distribution.

Index

Code Index:

NAME

Top

CGI::FormBuilder::Template::Fast - FormBuilder interface to CGI::FastTemplate

SYNOPSIS

Top

    my $form = CGI::FormBuilder->new(
        fields   => \@whatever,
        template => {
            type => 'Fast',
            root => '/path/to/templates',
            # use external files
            define => {
                form           => 'form.txt',
                field          => 'field.txt',
                invalid_field  => 'invalid_field.txt',
            },
            # or define inline
            define_nofile => {
                form => '<html><head></head><body>$START_FORM
                         <table>$FIELDS</table>$SUBMIT $END_FORM</body></html>',
                # etc.
            },
        },
   );

DESCRIPTION

Top

This engine adapts FormBuilder to use CGI::FastTemplate. Please read these docs carefully, as the usage differs from other template adapters in several important ways.

You will need to define three templates: form, field, and invalid_field. You can use define to point to external files (which is the recommended CGI::FastTemplate style), or define_nofile/ define_raw to define them inline. The templates in define_nofile take precedence over define_raw, and both of these take precedence over define.

    my $form = CGI::FormBuilder->new(
        # ...
        template => {
            type => 'FastTemplate',
            root => '/path/to/templates',
            define => {
                form           => 'form.txt',
                field          => 'field.txt',
                invalid_field  => 'invalid_field.txt',
            },
            # or, you can define templates directly
            define_nofile => {
                form => '<html><head></head><body>$START_FORM<table>'
                        '$FIELDS</table>$SUBMIT $END_FORM</body></html>',
                # etc.
            },
        },
        # ...
    );

If you use define with external templates, you will probably also want to define your template root directory with the root parameter.

Within each of the field templates, the following variables are available:

    $NAME         # $field->name
    $FIELD        # $field->tag   (HTML input tag)
    $VALUE        # $field->value (first value only!)
    $LABEL        # $field->label
    $COMMENT      # $field->comment
    $ERROR        # $field->error
    $REQUIRED     # $field->required ? 'required' : 'optional'

All the fields are processed in sequence; valid fields use the field template, and invalid fields the invalid_field template. The result from each of these is appended into the $FIELDS variable, which you should use in your form template. In the form template, you also have access to these variables:

    $TITLE        # title of the form
    $START_FORM   # opening form tag
    $SUBMIT       # the submit button
    $RESET        # the reset button
    $END_FORM     # closing form tag
    $JS_HEAD      # validation JavaScript

Note that since CGI::FastTemplate doesn't use anything other than simple scalar variables, there are no variables corrosponding to the lists that other engines have (e.g. fields or options lists in TT2 or Text::Template).

SEE ALSO

Top

CGI::FormBuilder, CGI::FormBuilder::Template, CGI::FastTemplate

AUTHOR

Top

Copyright (c) 2005-2006 Peter Eichman <peichman@cpan.org>. All Rights Reserved.

Maintained as part of CGI::FormBuilder by Nate Wiger <nate@wiger.org>.

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.

CGI-FormBuilder documentation Contained in the CGI-FormBuilder distribution. 
###########################################################################
# Copyright (c) 2000-2006 Nate Wiger <nate@wiger.org>. All Rights Reserved.
# Please visit www.formbuilder.org for tutorials, support, and examples.
###########################################################################

package CGI::FormBuilder::Template::Fast;


use Carp;
use strict;
use warnings;
no  warnings 'uninitialized';

use CGI::FormBuilder::Util;
use CGI::FastTemplate;
use base 'CGI::FastTemplate';

our $REVISION = do { (my $r='$Revision: 100 $') =~ s/\D+//g; $r };
our $VERSION = '3.0501';

sub new {
    my $self  = shift;
    my $class = ref($self) || $self;
    my $opt   = arghash(@_);

    my $t = CGI::FastTemplate->new($opt->{root});

    # turn off strict so that undef vars show up
    # as blank in the template output
    $t->no_strict;

    # define our templates
    $t->define(%{ $opt->{define} });
    $t->define_raw($opt->{define_raw});
    $t->define_nofile($opt->{define_nofile});    

    # jam $t info FB 'engine' container
    $opt->{engine} = $t;

    return bless $opt, $class;
}

sub engine {
    return shift()->{engine};
}

sub prepare {
    my $self = shift;
    my $form = shift;

    # a couple special fields
    my %tmplvar = $form->tmpl_param;

    # Go over the fields and process each one
    for my $field ($form->field) {
        # Extract value since used often
        my @value = $field->tag_value;

        # assign this field's variables
        my $ref = {
            NAME     => $field->name,
            FIELD    => $field->tag,
            VALUE    => $value[0],       # the VALUE tag can only hold first value!
            LABEL    => $field->label,
            REQUIRED => ($field->required ? 'required' : 'optional'),
            ERROR    => $field->error,
            COMMENT  => $field->comment,
        };
        $self->{engine}->assign($ref);

        # TODO: look for special templates based on field name or type?
        if ($field->invalid) {
            $self->{engine}->parse(FIELDS => '.invalid_field');
        } else {
            $self->{engine}->parse(FIELDS => '.field');
        }

        $self->{engine}->clear_href;        
    }

    # a couple special fields    
    $self->{engine}->assign({
        TITLE      => $form->title,
        JS_HEAD    => $form->script,
        START_FORM => $form->start . $form->statetags . $form->keepextras,
        SUBMIT     => $form->submit,
        RESET      => $form->reset,
        END_FORM   => $form->end,
        %tmplvar,
    });
    $self->{engine}->parse(FORM => 'form');

    return $self;
}

sub render {
    my $self = shift;
    return ${ $self->{engine}->fetch('FORM') };
}


# End of Perl code
1;
__END__