/ 
Mango-0.01000_06
River stage two • 9 direct dependents • 10 total dependents
/ Mango::Form

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.

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.

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, CGI::FormBuilder, FormValidator::Simple

AUTHOR

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