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

HTML::FormFu
HTML Form Creation, Rendering and Validation Framework

HTML::FormFu - HTML Form Creation, Rendering and Validation Framework


NAME

HTML::FormFu - HTML Form Creation, Rendering and Validation Framework


BETA SOFTWARE

Please note that this is beta software.

There may be API changes required before the 1.0 release. Any incompatible changes will first be discussed on the mailing list.

Work is still needed on the documentation, if you come across any errors or find something confusing, please give feedback via the mailing list.


SYNOPSIS


    use HTML::FormFu;

    my $form = HTML::FormFu->new;

    

    $form->load_config_file('form.yml');

    $form->process( $cgi_query );

    if ( $form->submitted_and_valid ) {

        # do something with $form->params

    }

    else {

        # display the form

        $template->param( form => $form );

    }

If you're using Catalyst, a more suitable example might be:


    package MyApp::Controller::User;

    use strict;

    use base 'Catalyst::Controller::HTML::FormFu';

    

    sub user : Chained CaptureArgs(1) {

        my ( $self, $c, $id ) = @_;

        

        my $rs = $c->model('Schema')->resultset('User');

        

        $c->stash->{user} = $rs->find( $id );

        

        return;

    }

    

    sub edit : Chained('user') Args(0) FormConfig {

        my ( $self, $c ) = @_;

        

        my $form = $c->stash->{form};

        my $user = $c->stash->{user};

        

        if ( $form->submitted_and_valid ) {

            

            $form->save_to_model( $user );

            

            $c->res->redirect( $c->uri_for( "/user/$id" ) );

            return;

        }

        

        $form->defaults_from_model( $user )

            if ! $form->submitted;

        

    }

Here's an example of a config file to create a basic login form (all examples here are YAML, but you can use any format supported by the Config::Any manpage), you can also create forms directly in your perl code, rather than using an external config file.


    ---

    action: /login

    indicator: submit

    auto_fieldset: 1

    

    elements:

      - type: Text

        name: user

        constraints: 

          - Required

      

      - type: Password

        name: pass

        constraints:

          - Required

      

      - type: Submit

        name: submit

    

    constraints:

      - SingleValue


DESCRIPTION

the HTML::FormFu manpage is a HTML form framework which aims to be as easy as possible to use for basic web forms, but with the power and flexibility to do anything else you might want to do (as long as it involves forms).

You can configure almost any part of formfu's behaviour and output. By default formfu renders ``XHTML 1.0 Strict'' compliant markup, with as little extra markup as possible, but with sufficient CSS class names to allow for a wide-range of output styles to be generated by changing only the CSS.

All methods listed below (except new) can either be called as a normal method on your $form object, or as an option in your config file. Examples will mainly be shown in YAML config syntax.

This documentation follows the convention that method arguments surrounded by square brackets [] are optional, and all other arguments are required.


BUILDING A FORM

new

Arguments: [\%options]

Return Value: $form

Create a new HTML::FormFu object.

Any method which can be called on the HTML::FormFu object may instead be passed as an argument to new.


    my $form = HTML::FormFu->new({

        action        => '/search',

        method        => 'GET',

        auto_fieldset => 1,

    });

load_config_file

Arguments: $filename

Arguments: \@filenames

Return Value: $form

Accepts a filename or list of file names, whose filetypes should be of any format recognized by the Config::Any manpage.

The content of each config file is passed to populate, and so are added to the form.

load_config_file may be called in a config file itself, so as to allow common settings to be kept in a single config file which may be loaded by any form.


    ---

    load_config_file:

      - file1

      - file2

YAML multiple documents within a single file. The document start marker is a line containing 3 dashes. Multiple documents will be applied in order, just as if multiple filenames had been given.

In the following example, multiple documents are taken advantage of to load another config file after the elements are added. (If this were a single document, the load_config_file would be called before elements, regardless of it's position in the file).


    ---

    elements:

      - name: one

      - name: two

    

    ---

    load_config_file: ext.yml

    

Like perl's C<open> function, relative-paths are resolved from the current 

working directory.

If you're using the FormConfig action controller in the Catalyst::Controller::HTML::FormFu manpage, see config_file_path.

See BEST PRACTICES for advice on organising config files.

config_callback

Arguments: \%options

If defined, the arguments are used to create a the Data::Visitor::Callback manpage object during load_config_file which may be used to pre-process the config before it is sent to populate

Default Value: not defined

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

populate

Arguments: \%options

Return Value: $form

Each option key/value passed may be any HTML::FormFu method-name and arguments.

Provides a simple way to set multiple values, or add multiple elements to a form with a single method-call.

Attempts to call the method-names in a semi-intelligent order (see the source of populate() in HTML::FormFu::ObjectUtil for details).

default_values

Arguments: \%defaults

Return Value: $form

Set multiple field's default values from a single hash-ref.

The hash-ref's keys correspond to a form field's name, and the value is passed to the field's default method.

This should be called after all fields have been added to the form, and before process is called (otherwise, call process again before rendering the form).

indicator

Arguments: $field_name

Arguments: \&coderef

If indicator is set to a fieldname, submitted will return true if a value for that fieldname was submitted.

If indicator is set to a code-ref, it will be called as a subroutine with the two arguments $form and $query, and its return value will be used as the return value for submitted.

If indicator is not set, submitted will return true if a value for any known fieldname was submitted.

auto_fieldset

Arguments: 1

Arguments: \%options

Return Value: $fieldset

This setting is suitable for most basic forms, and means you can generally ignore adding fieldsets yourself.

Calling $form->auto_fieldset(1) immediately adds a fieldset element to the form. Thereafter, $form->elements() will add all elements (except fieldsets) to that fieldset, rather than directly to the form.

To be specific, the elements are added to the last fieldset on the form, so if you add another fieldset, any further elements will be added to that fieldset.

Also, you may pass a hashref to auto_fieldset(), and this will be used to set defaults for the first fieldset created.

A few examples and their output, to demonstrate:

2 elements with no fieldset.


    ---

    elements:

      - type: Text

        name: foo

      - type: Text

        name: bar

    <form action="" method="post">

      <span class="text">

        <input name="foo" type="text" />

      </span>

      <span class="text">

        <input name="bar" type="text" />

      </span>

    </form>

2 elements with an auto_fieldset.


    ---

    auto_fieldset: 1

    elements:

      - type: Text

        name: foo

      - type: Text

        name: bar

    <form action="" method="post">

      <fieldset>

        <span class="text">

          <input name="foo" type="text" />

        </span>

        <span class="text">

          <input name="bar" type="text" />

        </span>

      </fieldset>

    </form>

The 3rd element is within a new fieldset


    ---

    auto_fieldset: { id: fs }

    elements:

      - type: Text

        name: foo

      - type: Text

        name: bar

      - type: Fieldset

      - type: Text

        name: baz

    <form action="" method="post">

      <fieldset id="fs">

        <span class="text">

          <input name="foo" type="text" />

        </span>

        <span class="text">

          <input name="bar" type="text" />

        </span>

      </fieldset>

      <fieldset>

        <span class="text">

          <input name="baz" type="text" />

        </span>

      </fieldset>

    </form>

Because of this behaviour, if you want nested fieldsets you will have to add each nested fieldset directly to its intended parent.


    my $parent = $form->get_element({ type => 'Fieldset' });

    

    $parent->element('fieldset');

form_error_message

Arguments: $string

Normally, input errors cause an error message to be displayed alongside the appropriate form field. If you'd also like a general error message to be displayed at the top of the form, you can set the message with form_error_message.

To change the markup used to display the message, edit the form_error_message template file.

form_error_message_xml

Arguments: $string

If you don't want your error message to be XML-escaped, use the form_error_message_xml method instead.

form_error_message_loc

Arguments: $localization_key

For ease of use, if you'd like to use the provided localized error message, set form_error_message_loc to the value form_error_message.

You can, of course, set form_error_message_loc to any key in your I18N file.

force_error_message

If true, forces the form_error_message to be displayed even if there are no field errors.

element_defaults

Arguments: \%defaults

Set defaults which will be added to every element of that type which is added to the form.

For example, to make every text element automatically have a size of 10, and make every textarea element automatically get a class-name of bigbox:


    element_defaults:

      Text:

        size: 10

      Textarea:

        add_attributes:

          class: bigbox

javascript

Arguments: [$javascript]

If set, the contents will be rendered within a script tag, inside the top of the form.

stash

Arguments: [\%private_stash]

Return Value: \%stash

Provides a hash-ref in which you can store any data you might want to associate with the form.


    ---

    stash:

      foo: value

      bar: value

elements

element

Arguments: $type

Arguments: \%options

Return Value: $element

Arguments: \@arrayref_of_types_or_options

Return Value: @elements

Adds a new element to the form. See CORE ELEMENTS in the HTML::FormFu::Element manpage for a list of core elements.

If you want to load an element from a namespace other than HTML::FormFu::Element::, you can use a fully qualified package-name by prefixing it with +.


    ---

    elements:

      - type: +MyApp::CustomElement

        name: foo

If a type is not provided in the \%options, the default Text will be used.

element is an alias for elements.

deflators

deflator

Arguments: $type

Arguments: \%options

Return Value: $deflator

Arguments: \@arrayref_of_types_or_options

Return Value: @deflators

A deflator may be associated with any form field, and allows you to provide $field-default> with a value which may be an object.

If an object doesn't stringify to a suitable value for display, the deflator can ensure that the form field receives a suitable string value instead.

See CORE DEFLATORS in the HTML::FormFu::Deflator manpage for a list of core deflators.

If a name attribute isn't provided, a new deflator is created for and added to every field on the form.

If you want to load a filter in a namespace other than HTML::FormFu::Deflator::, you can use a fully qualified package-name by prefixing it with +.

deflator is an alias for deflators.

insert_before

Arguments: $new_element, $existing_element

Return Value: $new_element

The 1st argument must be the element you want added, the 2nd argument must be the existing element that the new element should be placed before.


    my $new = $form->element(\%specs);

    

    my $position = $form->get_element({ type => $type, name => $name });

    

    $form->insert_before( $new, $position );

In the first line of the above example, the $new element is initially added to the end of the form. However, the insert_before method reparents the $new element, so it will no longer be on the end of the form. Because of this, if you try to copy an element from one form to another, it will 'steal' the element, instead of copying it. In this case, you must use clone:


    my $new = $form1->get_element({ type => $type1, name => $name1 })

                    ->clone;

    

    my $position = $form2->get_element({ type => $type2, name => $name2 });

    

    $form2->insert_before( $new, $position );

insert_after

Arguments: $new_element, $existing_element

Return Value: $new_element

The 1st argument must be the element you want added, the 2nd argument must be the existing element that the new element should be placed after.


    my $new = $form->element(\%specs);

    

    my $position = $form->get_element({ type => $type, name => $name });

    

    $form->insert_after( $new, $position );

In the first line of the above example, the $new element is initially added to the end of the form. However, the insert_after method reparents the $new element, so it will no longer be on the end of the form. Because of this, if you try to copy an element from one form to another, it will 'steal' the element, instead of copying it. In this case, you must use clone:


    my $new = $form1->get_element({ type => $type1, name => $name1 })

                    ->clone;

    

    my $position = $form2->get_element({ type => $type2, name => $name2 });

    

    $form2->insert_after( $new, $position );

insert_after


FORM LOGIC AND VALIDATION

HTML::FormFu provides several stages for what is traditionally described as validation. These are:

HTML::FormFu::Filter
HTML::FormFu::Constraint
HTML::FormFu::Inflator
HTML::FormFu::Validator
HTML::FormFu::Transformer

The first stage, the filters, allow for cleanup of user-input, such as encoding, or removing leading/trailing whitespace, or removing non-digit characters from a creditcard number.

All of the following stages allow for more complex processing, and each of them have a mechanism to allow exceptions to be thrown, to represent input errors. In each stage, all form fields must be processed without error for the next stage to proceed. If there were any errors, the form should be re-displayed to the user, to allow them to input correct values.

Constraints are intended for low-level validation of values, such as ``is this an integer?'', ``is this value within bounds?'' or ``is this a valid email address?''.

Inflators are intended to allow a value to be turned into an appropriate object. The resulting object will be passed to subsequent Validators and Transformers, and will also be returned by params and param.

Validators are intended for higher-level validation, such as business-logic and database constraints such as ``is this username unique?''. Validators are only run if all Constraints and Inflators have run without errors. It is expected that most Validators will be application-specific, and so each will be implemented as a separate class written by the HTML::FormFu user.

filters

filter

Arguments: $type

Arguments: \%options

Return Value: $filter

Arguments: \@arrayref_of_types_or_options

Return Value: @filters

If you provide a name or names value, the filter will be added to just that named field. If you do not provide a name or names value, the filter will be added to all fields already attached to the form.

See CORE FILTERS in the HTML::FormFu::Filter manpage for a list of core filters.

If you want to load a filter in a namespace other than HTML::FormFu::Filter::, you can use a fully qualified package-name by prefixing it with +.

filter is an alias for filters.

constraints

constraint

Arguments: $type

Arguments: \%options

Return Value: $constraint

Arguments: \@arrayref_of_types_or_options

Return Value: @constraints

See CORE CONSTRAINTS in the HTML::FormFu::Constraint manpage for a list of core constraints.

If a name attribute isn't provided, a new constraint is created for and added to every field on the form.

If you want to load a constraint in a namespace other than HTML::FormFu::Constraint::, you can use a fully qualified package-name by prefixing it with +.

constraint is an alias for constraints.

inflators

inflator

Arguments: $type

Arguments: \%options

Return Value: $inflator

Arguments: \@arrayref_of_types_or_options

Return Value: @inflators

See CORE INFLATORS in the HTML::FormFu::Inflator manpage for a list of core inflators.

If a name attribute isn't provided, a new inflator is created for and added to every field on the form.

If you want to load a inflator in a namespace other than HTML::FormFu::Inflator::, you can use a fully qualified package-name by prefixing it with +.

inflator is an alias for inflators.

validators

validator

Arguments: $type

Arguments: \%options

Return Value: $validator

Arguments: \@arrayref_of_types_or_options

Return Value: @validators

See CORE VALIDATORS in the HTML::FormFu::Validator manpage for a list of core validators.

If a name attribute isn't provided, a new validator is created for and added to every field on the form.

If you want to load a validator in a namespace other than HTML::FormFu::Validator::, you can use a fully qualified package-name by prefixing it with +.

validator is an alias for validators.

transformers

transformer

Arguments: $type

Arguments: \%options

Return Value: $transformer

Arguments: \@arrayref_of_types_or_options

Return Value: @transformers

See CORE TRANSFORMERS in the HTML::FormFu::Transformer manpage for a list of core transformers.

If a name attribute isn't provided, a new transformer is created for and added to every field on the form.

If you want to load a transformer in a namespace other than HTML::FormFu::Transformer::, you can use a fully qualified package-name by prefixing it with +.

transformer is an alias for transformers.


CHANGING DEFAULT BEHAVIOUR

render_processed_value

The default behaviour when re-displaying a form after a submission, is that the field contains the original unchanged user-submitted value.

If render_processed_value is true, the field value will be the final result after all Filters, Inflators and Transformers have been run. Deflators will also be run on the value.

If you set this on a field with an Inflator, but without an equivalent Deflator, you should ensure that the Inflators stringify back to a useable value, so as not to confuse / annoy the user.

Default Value: false

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

force_errors

Force a constraint to fail, regardless of user input.

If this is called at runtime, after the form has already been processed, you must called process in the HTML::FormFu manpage again before redisplaying the form to the user.

Default Value: false

This method is a special 'inherited accessor', which means it can be set on the form, a block element, an element or a single constraint. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.


FORM ATTRIBUTES

All attributes are added to the rendered form's start tag.

attributes

attrs

Arguments: [%attributes]

Arguments: [\%attributes]

Return Value: $form

Accepts either a list of key/value pairs, or a hash-ref.


    ---

    attributes:

      id: form

      class: fancy_form

As a special case, if no arguments are passed, the attributes hash-ref is returned. This allows the following idioms.


    # set a value

    $form->attributes->{id} = 'form';

    

    # delete all attributes

    %{ $form->attributes } = ();

attrs is an alias for attributes.

attributes_xml

attrs_xml

Provides the same functionality as attributes, but values won't be XML-escaped.

attrs_xml is an alias for attributes_xml.

add_attributes

add_attrs

Arguments: [%attributes]

Arguments: [\%attributes]

Return Value: $form

Accepts either a list of key/value pairs, or a hash-ref.


    $form->add_attributes( $key => $value );

    $form->add_attributes( { $key => $value } );

All values are appended to existing values, with a preceding space character. This is primarily to allow the easy addition of new names to the class attribute.


    $form->attributes({ class => 'foo' });

    

    $form->add_attributes({ class => 'bar' });

    

    # class is now 'foo bar'

add_attrs is an alias for add_attributes.

add_attributes_xml

add_attrs_xml

Provides the same functionality as add_attributes, but values won't be XML-escaped.

add_attrs_xml is an alias for add_attributes_xml.

del_attributes

del_attrs

Arguments: [%attributes]

Arguments: [\%attributes]

Return Value: $form

Accepts either a list of key/value pairs, or a hash-ref.


    $form->del_attributes( $key => $value );

    $form->del_attributes( { $key => $value } );

All values are removed from the attribute value.


    $form->attributes({ class => 'foo bar' });

    

    $form->del_attributes({ class => 'bar' });

    

    # class is now 'foo'

del_attrs is an alias for del_attributes.

del_attributes_xml

del_attrs_xml

Provides the same functionality as del_attributes, but values won't be XML-escaped.

del_attrs_xml is an alias for del_attributes_xml.

The following methods are shortcuts for accessing attributes keys.

id

Arguments: [$id]

Return Value: $id

Get or set the form's DOM id.

Default Value: none

action

Arguments: [$uri]

Return Value: $uri

Get or set the action associated with the form. The default is no action, which causes most browsers to submit to the current URI.

Default Value: ``''

enctype

Arguments: [$enctype]

Return Value: $enctype

Get or set the encoding type of the form. Valid values are application/x-www-form-urlencoded and multipart/form-data.

If the form contains a File element, the enctype is automatically set to multipart/form-data.

method

Arguments: [$method]

Return Value: $method

Get or set the method used to submit the form. Can be set to either ``post'' or ``get''.

Default Value: ``post''


CSS CLASSES

auto_id

Arguments: [$string]

If set, then all form fields will be given an auto-generated id attribute, if it doesn't have one already.

The following character substitution will be performed: %f will be replaced by $form-id>, %n will be replaced by $field-name>.

Default Value: not defined

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

auto_label

Arguments: [$string]

If set, then all form fields will be given an auto-generated name, if it doesn't have one already.

The following character substitution will be performed: %f will be replaced by $form-id>, %n will be replaced by $field-name>.

The generated string will be passed to localize to create the label.

Default Value: not defined

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

auto_error_class

Arguments: [$string]

If set, then all form errors will be given an auto-generated class-name.

The following character substitution will be performed: %f will be replaced by $form-id>, %n will be replaced by $field-name>, %t will be replaced by lc( $field-type )>, %s will be replaced by $error-stage>.

Default Value: 'error_%s_%t'

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

auto_error_message

Arguments: [$string]

If set, then all form fields will be given an auto-generated message, if it doesn't have one already.

The following character substitution will be performed: %f will be replaced by $form-id>, %n will be replaced by $field-name>, %t will be replaced by lc( $field-type )>.

The generated string will be passed to localize to create the message.

Default Value: 'form_%t_error'

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

auto_constraint_class

Arguments: [$string]

If set, then all form fields will be given an auto-generated class-name for each associated constraint.

The following character substitution will be performed: %f will be replaced by $form-id>, %n will be replaced by $field-name>, %t will be replaced by lc( $field-type )>.

Default Value: not defined

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

auto_inflator_class

Arguments: [$string]

If set, then all form fields will be given an auto-generated class-name for each associated inflator.

The following character substitution will be performed: %f will be replaced by $form-id>, %n will be replaced by $field-name>, %t will be replaced by lc( $field-type )>.

Default Value: not defined

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

auto_validator_class

Arguments: [$string]

If set, then all form fields will be given an auto-generated class-name for each associated validator.

The following character substitution will be performed: %f will be replaced by $form-id>, %n will be replaced by $field-name>, %t will be replaced by lc( $field-type )>.

Default Value: not defined

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

auto_transformer_class

Arguments: [$string]

If set, then all form fields will be given an auto-generated class-name for each associated validator.

The following character substitution will be performed: %f will be replaced by $form-id>, %n will be replaced by $field-name>, %t will be replaced by lc( $field-type )>.

Default Value: not defined

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.


LOCALIZATION

languages

Arguments: [\@languages]

A list of languages which will be passed to the localization object.

Default Value: ['en']

localize_class

Arguments: [$class_name]

Classname to be used for the default localization object.

Default Value: 'HTML::FormFu::I18N'

localize

loc

Arguments: [$key, @arguments]

Compatible with the maketext method in the Locale::Maketext manpage.


PROCESSING A FORM

query

Arguments: [$query_object]

Arguments: \%params

Provide a CGI compatible query object or a hash-ref of submitted names/values. Alternatively, the query object can be passed directly to the process object.

query_type

Arguments: [$query_type]

Set which module is being used to provide the query.

The the Catalyst::Controller::HTML::FormFu manpage automatically sets this to Catalyst.

Valid values are CGI, Catalyst and CGI::Simple.

Default Value: 'CGI'

process

Arguments: [$query_object]

Arguments: [\%params]

Process the provided query object or input values. This must be called before calling any of the methods listed under SUBMITTED FORM VALUES AND ERRORS and MODIFYING A SUBMITTED FORM.

It's not necessary to call process before printing the form or calling render.


SUBMITTED FORM VALUES AND ERRORS

submitted

Returns true if the form has been submitted. See indicator for details on how this is computed.

submitted_and_valid

Shorthand for $form->submitted && !$form->has_errors

params

Return Value: \%params

Returns a hash-ref of all valid input for which there were no errors.

param

Arguments: [$field_name]

Return Value: $input_value

Return Value: @valid_names

A (readonly) CGI compatible method.

If a field name is given, in list-context returns any valid values submitted for that field, and in scalar-context returns only the first of any valid values submitted for that field.

If no argument is given, returns a list of all valid input field names without errors.

Passing more than 1 argument is a fatal error.

valid

Arguments: [$field_name]

Return Value: @valid_names

Return Value: $bool

If a field name if given, returns true if that field had no errors and false if there were errors.

If no argument is given, returns a list of all valid input field names without errors.

has_errors

Arguments: [$field_name]

Return Value: @names

Return Value: $bool

If a field name if given, returns true if that field had errors and false if there were no errors.

If no argument is given, returns a list of all input field names with errors.

get_errors

Arguments: [%options]

Arguments: [\%options]

Return Value: \@errors

Returns an array-ref of exception objects from all fields in the form.

Accepts both name, type and stage arguments to narrow the returned results.


    $form->get_errors({

        name  => 'foo',

        type  => 'Regex',

        stage => 'constraint'

    });

get_error

Arguments: [%options]

Arguments: [\%options]

Return Value: $error

Accepts the same arguments as get_errors, but only returns the first error found.


MODIFYING A SUBMITTED FORM

add_valid

Arguments: $name, $value

Return Value: $value

The provided value replaces any current value for the named field. This value will be returned in subsequent calls to params and param and the named field will be included in calculations for valid.

clear_errors

Deletes all errors from a submitted form.


RENDERING A FORM

render

Return Value: $string

start

Return Value: $string

Returns the form start tag, and any output of form_error_message and javascript.

Implicitly uses the tt render_method.

end

Return Value: $string

Returns the form end tag.

Implicitly uses the tt render_method.

hidden_fields

Return Value: $string

Returns all hidden form fields.


ADVANCED CUSTOMISATION

By default, formfu renders ``XHTML 1.0 Strict'' compliant markup, with as little extra markup as possible, but with sufficient CSS class names to allow for a wide-range of output styles to be generated by changing only the CSS.

If you wish to customise the markup, you'll need to tell HTML::FormFu to use an external rendering engine, such as Template Toolkit or the Template::Alloy manpage. See render_method and tt_module for details.

Even if you set HTML::FormFu to use Template::Toolkit to render, the forms, HTML::FormFu can still be used in conjunction with whichever other templating system you prefer to use for your own page layouts, whether it's the HTML::Template manpage: <TMPL_VAR form>, Petal: <form tal:replace="form"></form> or the Template::Magic manpage: <!-- {form} -->.

render_method

Default Value: string

Can be set to tt to generate the form with external template files.

To customise the markup, you'll need a copy of the template files, local to your application. See Installing the TT templates in the HTML::FormFu::Manual::Cookbook manpage for further details.

You can customise the markup for a single element by setting that element's render_method to tt, while the rest of the form uses the default string render-method. Note though, that if you try setting the form or a Block's render_method to tt, and then set a child element's render_method to string, that setting will be ignored, and the child elements will still use the tt render-method.


    ---

    elements:

      - name: foo

        render_method: tt

        filename: custom_field

      

      - name: bar

    

    # in this example, 'foo' will use a custom template,

    # while bar will use the default 'string' rendering method

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

filename

Change the template filename used for the form.

Default Value: ``form''

tt_args

Arguments: [\%constructor_arguments]

Accepts a hash-ref of arguments passed to render_method, which is called internally by render.

Within tt, the keys RELATIVE and RECURSION are overridden to always be true, as these are a basic requirement for the Template engine.

The system directory containing HTML::FormFu's template files is always added to the end of INCLUDE_PATH, so that the core template files will be found. You only need to set this yourself if you have your own copy of the template files for customisation purposes.

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

add_tt_args

Arguments: [\%constructor_arguments]

Ensures that the hash-ref argument is merged with any existing hash-ref value of tt_args.

tt_module

Default Value: Template

The module used when render_method is set to tt. Should provide an interface compatible with Template.

This method is a special 'inherited accessor', which means it can be set on the form, a block element or a single element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, through any block elements and up to the form, searching for a defined value.

render_data

Usually called implicitly by render. Returns the data structure that would normally be passed onto the string or tt render-methods.

render_data_non_recursive

Like render_data, but doesn't include the data for any child-elements.


INTROSPECTION

get_elements

Arguments: [%options]

Arguments: [\%options]

Return Value: \@elements

Returns all top-level elements in the form (not recursive). See get_all_elements for a recursive version.

Accepts both name and type arguments to narrow the returned results.


    $form->get_elements({

        name => 'foo',

        type => 'Radio',

    });

get_element

Arguments: [%options]

Arguments: [\%options]

Return Value: $element

Accepts the same arguments as get_elements, but only returns the first element found.

See get_all_element for a recursive version.

get_all_elements

Arguments: [%options]

Arguments: [\%options]

Return Value: \@elements

Returns all elements in the form recursively.

Optionally accepts both name and type arguments to narrow the returned results.


    # return all Text elements

    

    $form->get_all_elements({

        type => 'Text',

    });

See get_elements for a non-recursive version.

get_all_element

Arguments: [%options]

Arguments: [\%options]

Return Value: $element

Accepts the same arguments as get_all_elements, but only returns the first element found.


    # return the first Text field found, regardless of whether it's 

    # within a fieldset or not

    

    $form->get_all_element({

        type => 'Text',

    });

See get_all_elements for a non-recursive version.

get_fields

Arguments: [%options]

Arguments: [\%options]

Return Value: \@elements

Returns all fields in the form (specifically, all elements which have a true is_field in the HTML::FormFu::Element manpage value.

Accepts both name and type arguments to narrow the returned results.


    $form->get_fields({

        name => 'foo',

        type => 'Radio',

    });

get_field

Arguments: [%options]

Arguments: [\%options]

Return Value: $element

Accepts the same arguments as get_fields, but only returns the first field found.

get_deflators

Arguments: [%options]

Arguments: [\%options]

Return Value: \@deflators

Returns all top-level deflators from all fields.

Accepts both name and type arguments to narrow the returned results.


    $form->get_deflators({

        name => 'foo',

        type => 'Strftime',

    });

get_deflator

Arguments: [%options]

Arguments: [\%options]

Return Value: $element

Accepts the same arguments as get_deflators, but only returns the first deflator found.

get_filters

Arguments: [%options]

Arguments: [\%options]

Return Value: \@filters

Returns all top-level filters from all fields.

Accepts both name and type arguments to narrow the returned results.


    $form->get_filters({

        name => 'foo',

        type => 'LowerCase',

    });

get_filter

Arguments: [%options]

Arguments: [\%options]

Return Value: $filter

Accepts the same arguments as get_filters, but only returns the first filter found.

get_constraints

Arguments: [%options]

Arguments: [\%options]

Return Value: \@constraints

Returns all constraints from all fields.

Accepts both name and type arguments to narrow the returned results.


    $form->get_constraints({

        name => 'foo',

        type => 'Equal',

    });

get_constraint

Arguments: [%options]

Arguments: [\%options]

Return Value: $constraint

Accepts the same arguments as get_constraints, but only returns the first constraint found.

get_inflators

Arguments: [%options]

Arguments: [\%options]

Return Value: \@inflators

Returns all inflators from all fields.

Accepts both name and type arguments to narrow the returned results.


    $form->get_inflators({

        name => 'foo',

        type => 'DateTime',

    });

get_inflator

Arguments: [%options]

Arguments: [\%options]

Return Value: $inflator

Accepts the same arguments as get_inflators, but only returns the first inflator found.

get_validators

Arguments: [%options]

Arguments: [\%options]

Return Value: \@validators

Returns all validators from all fields.

Accepts both name and type arguments to narrow the returned results.


    $form->get_validators({

        name => 'foo',

        type => 'Callback',

    });

get_validator

Arguments: [%options]

Arguments: [\%options]

Return Value: $validator

Accepts the same arguments as get_validators, but only returns the first validator found.

get_transformers

Arguments: [%options]

Arguments: [\%options]

Return Value: \@transformers

Returns all transformers from all fields.

Accepts both name and type arguments to narrow the returned results.


    $form->get_transformers({

        name => 'foo',

        type => 'Callback',

    });

get_transformer

Arguments: [%options]

Arguments: [\%options]

Return Value: $transformer

Accepts the same arguments as get_transformers, but only returns the first transformer found.

clone

Returns a deep clone of the <$form> object.

Because of scoping issues, code references (such as in Callback constraints) are copied instead of cloned.


BEST PRACTICES

It is advisable to keep application-wide (or global) settings in a single config file, which should be loaded by each form.

See load_config_file.


COOKBOOK

the HTML::FormFu::Manual::Cookbook manpage

UNICODE

the HTML::FormFu::Manual::Unicode manpage


EXAMPLES

vertically-aligned CSS

The distribution directory examples/vertically-aligned contains a form with example CSS for a ``vertically aligned'' theme.

This can be viewed by opening the file vertically-aligned.html in a web-browser.

If you wish to experiment with making changes, the form is defined in file vertically-aligned.yml, and the HTML file can be updated with any changes by running the following command (while in the distribution root directory).


    perl examples/vertically-aligned/vertically-aligned.pl

This uses the Template Toolkit file vertically-aligned.tt, and the CSS is defined in files vertically-aligned.css and vertically-aligned-ie.css.


SUPPORT

Project Page:

http://code.google.com/p/html-formfu/

Mailing list:

http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu

Mailing list archives:

http://lists.scsys.co.uk/pipermail/html-formfu/

The HTML::Widget archives between January and May 2007 also contain discussion regarding HTML::FormFu.


BUGS

Please submit bugs / feature requests to http://code.google.com/p/html-formfu/issues/list (preferred) or http://rt.perl.org.


SUBVERSION REPOSITORY

The publicly viewable subversion code repository is at http://html-formfu.googlecode.com/svn/trunk/HTML-FormFu.

If you wish to contribute, you'll need a google account. Then just ask on the mailing list for commit access, giving the email address your account uses.

If you wish to contribute but for some reason really don't want to sign up for a google account, please post patches to the mailing list (although you'll have to wait for someone to commit them).

If you have commit permissions, use the HTTPS repository url: https://html-formfu.googlecode.com/svn/trunk/HTML-FormFu


SEE ALSO

the HTML::FormFu::Imager manpage

the Catalyst::Controller::HTML::FormFu manpage

the DBIx::Class::FormFu manpage


AUTHORS

Carl Franks


CONTRIBUTORS

Brian Cassidy

Ruben Fonseca

Daisuke Maki

Andreas Marienborg

Mario Minati

Based on the original source code of the HTML::Widget manpage, by Sebastian Riedel, sri@oook.de.


LICENSE

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy