Mango::Form - Module representing an input form
my $form = Mango::Form->new({ source => 'path/to/some/config.yml' });
Mango::Form renders forms using CGI::FormBuilder and validates data using FormValidator::Simple, all from a single configuration 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.
fields
constraints
--- 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
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:
UNIQUE
- 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; });
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:
messages
- 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"
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:
localizer
$form->localizer(sub { my $message, $args) = @_; ...localize magic });
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(@_); } });
A string containing the path to the config file, or a hash reference containing the same configuration data.
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. :-)
A code reference to be used to localize the field labels, buttons and messages.
A hash reference containing methods to be used to determine if s fields values already exists.
A hash reference containing methods to be used to determine field value uniqueness.
A hash reference containing the default form field values.
Gets/sets the action for the current form.
Creates and returns a clone of the current form.
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... };
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.
Gets/sets the code reference used to localize form field labels, buttons and messages.
$form->localizer( sub { my $self = shift; return MyApp->localize(@_); } );
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);
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.
source
Returns the html source for the current form.
Returns true if the form has been submitted.
if ($form->submitted) { ... };
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... };
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; ... };
Gets/sets the current form fields values.
my %values = $form->values; $form->values({ field11 => 'Foo', field2 => 2 });
Mango::Form::Results, CGI::FormBuilder, FormValidator::Simple
Christopher H. Laco CPAN ID: CLACO claco@chrislaco.com http://today.icantfocus.com/blog/
To install Mango, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mango
CPAN shell
perl -MCPAN -e shell install Mango
For more information on module installation, please visit the detailed CPAN module installation guide.