Creating Forms

Most of the time, a web developper is creating forms and checking their values. Most time, what needs to be done with the data is trivial by contrast with the code needed to create the form and validate every field.

But this is, most of the time, a simple task, that includes validate every field with a regexp, and create the form isn't rocket science also.

In my case, I like that every form in a site looks the same, so if I have several forms in a single site, more than copy validation code, I would be copying also form templates.

But what I really, really wanted was to concentrate on the specifics of data processing. What I wanted to do was: 

if (my $fdata=form()) {

 # This is my work, I don't care about anything else

}


This obviously, is too simplist, as there are no way I could do this to every form without rewrite form everytime. So, after a long code-use-recode cycle, I got to this syntax, that you can use to create forms with the Mason Framework: 


my $fields=[
   { name => 'test', # the field name
     value => 'somevalue', #the initial value
     type => 'input', #the field type
     valid => '^\d+$',
   }
  ];
my $formargs={fields=>$fields, title=>'Some title'};
if (my $fdata=$mf->form(args=>$formargs)) {
  $data={testvalue=>$fdata->{test}};
  $mf->template('showformtest', add_data=>$data);
}


What I get from this? A form is created and show for me, every field in the form is validated, and only when the values are valid the form will return a data hashref. Until that happen $mf->form() will return undef, and everything related to the form is shown to the user.

If it get inside that if, the fields are already valid, so all I need to do is use the data.

form Arguments

The $mf->form() method will get a named argument args, that should be an hashref to a structure that need to include a fields key, and can optionally include also title, sendtxt, errormessage, verifyrec and extrabuttons.

fields

$formargs->{fields} must be an arrayref of hashs. Every value in the fields represents a different field on the form. There are a special field type, named section, that represents a form section. The sections only need a label and a type. This represents a complete section: 



{ type => 'section',
  label => 'Personal Data',
}


Every other field can have the following data:
  • type: the field type. The default to this is input. It's this value that define the how de field will be shown. If no special code is written to this $field->{type}, the template form/fields/$field->{type} will be parsed with the $field as data to create the html for this field.
  • name: the field name. If this value is not set, the field will (probably) shown anyway, but as the field will now have a name, no value will be submited, and every valid will fail (unless empty/undef are valid values).
  • label: With the default templates (and usually), near the field will be shown a label, that tell the user the field name. That shown value is given by this.
  • comment: The default templates, at this moment, ignore this value, but probably in the near future, this will be show next to the field, as comment. This value is given to form/field or form/fieldneeded template.
  • needed: This value determines which template will be used to show the form field (including label and comment). If this value is false (or absent), the template used will be form/field. If it is true, form/fieldneeded will be used. If true, the form will only return if this field have a value.
  • value: This is the default value, the value shown in the form, the first time the form is shown. If after submit any field have invalid values, the values submitted will be used.
  • viewonly: If this is present and true, every change made in the field value will be ignored.
  • options: Some field types need options, as it is the case of SELECT. But even those fields that don't need options can have an options value. This is expected to be an hashref, with values as keys and related labels as values. If this exists, only keys on the options hash will be acepted. This options will be used to create the html code to the field for some field types (as SELECT).
  • valid: This is an regexp (as string). This will be used to validate the values submited. NOTE: This will only be used if the field have a value. To make sure that the field have a value you need to have needed => 1 in the field definition.


title

the formargs title defined the title value that will be given to the form template.

sendtxt

sendtxt is the value of the submit default button. If this is not set, "<?=lng:SAVE?>" will be used.

errormessage

This is the message that will be shown if the form values have any error. This value can include the variable <?=error?>, where the field(s) that have errors will be.

If this value is not set, "<?=lng:FORMERROR?>" will be used.

verifyrec

verifyrec is expected to be the path to a component mason that will return false if the record is valid and an error message if it is not. This can be used to verify data conflicts, for example.

This component will get as paraments $mf and $fields, a ref to the Mason framework object, and an arrayref to the fields.

extrabuttons

Extrabuttons is expected to be an arrayref to hashs, where each hash can have a name and value. This will be used to generate adicional buttons on the form. This extrabuttons will be added to the data returned by $mf->form(...).

See also