view release on metacpan or  search on metacpan

lib/CGI/FormMagick.pm  view on Meta::CPAN

    <page name="RoomType" post-event="check_availability">
      <description>
        Please provide us with details of your preferred room.
      </description>
      <field> ... </field>
      <field> ... </field>
      <field> ... </field>
    </page>


=head1 FIELDS

Fields are the most important part of the form definition.  Several
types of HTML fields are supported, and each one has various attributes
associated with it.

=head2 Field types

You can specify the type of HTML field to be generated using the type
attribute:

    <field type="...">

The following field types are supported:

=over 4

=item text 

A plain text field.  You may optionally use the size attribute to modify
the size of the field displayed.  To restrict the length of data entered
by the user, use the maxlength() validation routine.

=item select 

A dropdown list.  You must provide the options attribute to specify the
contents of the list (see below for the format of this attribute).  If
you set the multiple attribute to 1, multiple selections will be
enabled.  The optional size attribute sets the number of items displayed
at once.

=item radio 

Radio buttons allow users to choose one item from a group.  This field
type requires the options attribute (as for select, above).

=item checkbox 

This field type provides a simple check box for yes/no questions.  The
checked attribute is optional, but if set to 1 will make the checkbox
checked by default.

=item password

The password field type is like a text field, but obscures the data
typed in by the user.

=item file

This field type allows the upload of a file by the user.

=item textarea

A multi-line text field allowing the input of blocks of text. Defaults
to 5 rows and 60 columns, but you can specify "rows" and "cols" arguments
to change that.

=item literal

A field that is just printed literally.  Useful if you want to just print out a 
non-editable bit of text in the same sort of layout as the other fields in the form.

=back

=head2 Field sub-elements

The following elements may be nested within a field:

=over 4

=item * 

label (a short description; required)

=item * 

description (a more verbose description; optional)

=back


=head2 Other field attributes

Fields must ALWAYS have a type (described in the previous section) and 
an id attribute, which is a unique name for 
the field.  Each type of field may have additional required attributes,
and may support other optional attributes.

Here is a list of optional attributes for fields:

=over 4

=item value 

A default value to fill in; see below for more information on the format
of this field.

=item validation 

a list of validation functions; see L<CGI::FormMagick::Validator> for more
information on this subject.

=item validation-error-message

an error message to present to the user if validation fails.
CGI::FormMagick::Validator provides one by default, but you may prefer
to override it.

=item options