NAME

Mango::Form - Module representing an input form

SYNOPSIS

    my $form = Mango::Form->new({
        source => 'path/to/some/config.yml'
    });

DESCRIPTION

Mango::Form renders forms using CGI::FormBuilder and validates data using FormValidator::Simple, all from a single configuration format.

FORM FILE FORMAT

The form file format is YAML. The top level options are passed directly to CGI::FormBuilder. The collection of fields are parsed out into FormBuilder field specs and sent to FormBuilder. The constraints are FormValidator::Simple constraint names.

    ---
    name: form_name
    method: POST
    javascript: 0
    stylesheet: 1
    sticky: 1
    submit: LABEL_CREATE
    fields:
      - sku:
          type: text
          size: 25
          maxlength: 25
          constraints:
            - NOT_BLANK
            - LENGTH, 1, 25
            - UNIQUE
      - name:
          type: text
          size: 25
          maxlength: 25
          constraints:
            - NOT_BLANK
            - LENGTH, 1, 25
      - description:
          type: text
          size: 50
          maxlength: 100
          constraints:
            - NOT_BLANK
            - LENGTH, 1, 100
      - price:
          type: text
          size: 25
          maxlength: 12
          constraints:
            - NOT_BLANK
            - DECIMAL, 9, 2
      - tags:
          type: textarea

constraints

Each constraint in the constraints collection is the name of a FormValidator::Simple validation command. You can pass options to that command by simply adding to that line separated by commas.

The UNIQUE constraint is specific to Mango::Form. When specified, it will run the code reference associated with the current field. You can use a different field name by passing it as another option:

    - sku:
        type: text
        size: 25
        maxlength: 25
        constraints:
          - NOT_BLANK
          - LENGTH, 1, 25
          - UNIQUE, part_number

By default, all UNIQUE constraints will fail, unless you tell the form how to validate that field. You can do this by calling "unique":

    $form->unique('sku', sub {
        my ($self, $field, $value) = @_;
        ...determine if sku exists
        return $exists ? 1 : 0;
    });

messages

The messages default to FIELDNAME_CONSTRAINTNAME, which is then localized. In the example above, the error message returned when the sku was blank would be SKU_NOT_BLANK. When the price failed the decimal check, PRICE_DECIMAL is returned, etc.

You can override these defaults to use your own message key, or provide a complete text message itself using the messages collection and assigning the new message to the same constraint name:

    - sku:
        type: text
        size: 25
        maxlength: 25
        constraints:
          - NOT_BLANK
          - LENGTH, 1, 25
          - UNIQUE, part_number
        messages:
          NOT_BLANK: "sku cannot be blank"
          LENGTH: "sku is too long"
          UNIQUE: "sku already exists"

localization

When running by itself, messages and field labels are localized using Mango::I18N. While running under the Mango Catalyst controllers, $c->localize is used to localize the messages and labels, which will use MyApp::I18N or MyApp::L10N. You can also use your own localizer by passing a code reference into the localizer property:

    $form->localizer(sub {
        my $message, $args) = @_;
        ...localize magic
    });

CONSTRUCTOR

new

Arguments: \%options

Creates a new Mano::Form object. The following options are available:

    my $form = Mango::Form->new({
        source => 'thisform.yml',
        unique => {
            field => \&field_is_unique
        },
        localizer => sub {
            MyApp->localize(@_);
        }
    });

source

A string containing the path to the config file, or a hash reference containing the same configuration data.

validator

 An instance of the validator to be used. This is an instance of
 FormValidator::Simple by default. Using anything else at this time will
 probably not work. :-)

localizer

A code reference to be used to localize the field labels, buttons and messages.

exists

A hash reference containing methods to be used to determine if s fields values already exists.

unique

A hash reference containing methods to be used to determine field value uniqueness.

values

A hash reference containing the default form field values.

METHODS

action

Arguments: $action

Gets/sets the action for the current form.

clone

Creates and returns a clone of the current form.

exists

Arguments: $field, \&code

Gets/sets the code reference to be used to determine if a fields value already exists.

    $form->exists('field')->($self, 'field', 'value');
    $form->exists('field', sub {
        my ($self, $field, $value) = @_;
        ...exists magic...
    };

field

Arguments: $name or %options

Gets/sets a form fields information and other options.

    my $field = $form->field('sku');
    $form->field(name => 'sku', options => [...]);

See "field" in CGI::FormBuilder for more information.

localizer

Arguments \&sub

Gets/sets the code reference used to localize form field labels, buttons and messages.

    $form->localizer(
        sub {
            my $self = shift;
            return MyApp->localize(@_);
        }
    );

params

Arguments: $object

Gets/sets the object to read params from. This can be a CGI object, the Catalyst::Request object, or any other object that supports the param() method.

    $form->params($r);

parse

Arguments: $source

Parses the specified configuration and creates the appropriate forms, fields, constraints and messages.

    $form->parse('/myform.yml');

source can be either a string containing the configuration file name, or a hash reference containing the same data structure.

render

Returns the html source for the current form.

submitted

Returns true if the form has been submitted.

    if ($form->submitted) {
        ...
    };

unique

Arguments: $field, \&code

Gets/sets the code reference to be used to determine if a field value is unique or not.

    $form->unique('field')->($self, 'field', 'value');
    $form->unique('field', sub {
        my ($self, $field, $value) = @_;
        ...unique magic...
    };

validate

Validates the current for values against the constraints and returns a Mango::Form::Results instance.

    my $results = $form->validate;
    if ($results->success) {
        ...save to db...
    } else {
        my $errors = $results->errors;
        ...
    };

values

Arguments: \%values

Gets/sets the current form fields values.

    my %values = $form->values;
    $form->values({
        field11 => 'Foo',
        field2  => 2
    });

SEE ALSO

Mango::Form::Results, HTML::FormFu

AUTHOR

    Christopher H. Laco
    CPAN ID: CLACO
    claco@chrislaco.com
    http://today.icantfocus.com/blog/

cpanm Mango

perl -MCPAN -e shell
install Mango