/ 
Mango-0.01000_04
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.

process

Creates an XML::Feed of the specific type, writes it to the response body, and changes the content type. There is usually no reason to call this method directly. Forward to this view instead:

$c->forward($c->view('Atom'));

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/