
###########################################################################
# 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;

=head1 NAME

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

=head1 SYNOPSIS

    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.
            },
        },
   );

=cut

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__

=head1 DESCRIPTION

This engine adapts B<FormBuilder> to use C<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: C<form>, C<field>, and
C<invalid_field>. You can use C<define> to point to external files
(which is the recommended C<CGI::FastTemplate> style), or C<define_nofile>/
C<define_raw> to define them inline. The templates in C<define_nofile>
take precedence over C<define_raw>, and both of these take precedence
over C<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 C<define> with external templates, you will probably
also want to define your template root directory with the C<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 
C<field> template, and invalid fields the C<invalid_field> template.
The result from each of these is appended into the C<$FIELDS>
variable, which you should use in your C<form> template. In the 
C<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 C<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. C<fields> or C<options> 
lists in C<TT2> or C<Text::Template>).

=head1 SEE ALSO

L<CGI::FormBuilder>, L<CGI::FormBuilder::Template>, L<CGI::FastTemplate>

=head1 AUTHOR

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

Maintained as part of C<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.

=cut
