![]() |
![]()
| ![]() |
![]()
NAMEHTML::Field - Generation of HTML form elementsSYNOPSISuse HTML::Field; ########## Creation of Field objects ############## # A text field: my $field1 = HTML::Field->new('Textfield', name => 'fieldname', value => 'current value', default => 'default value', size => 15, maxlength => 15 ); # A Pasword field (has the same attributes as 'Textfield'): my $field2 = HTML::Field->new('Passwd', name => 'fieldname', value => 'current value', default => 'default value', size => 15, maxlength => 15 ); # A hidden field: my $hidden = HTML::Field->new('Hidden', name => 'sid', value => 'cgiasf25k', default => undef ); # A text area: my $area = HTML::Field->new('Textarea', name => 'address', cols => 40, rows => 4 ); # A 'select' tag. Options are given in an array reference; labels are # given in a hash keyed by the options: my $select = HTML::Field->new('Select', name => 'select_color', options => [qw(red yellow brown)], default => 'red', labels => {red => 'Color of apples', yellow => 'Color of mangos!', brown => 'Color of chocolate'}, multiple => undef, # Multiple is either true or false size => 1 ); # Size of select box # A radio button. Note that it will generate the HTML for all of its # options, and those will be named as 'name_option' my $radio_buttons = HTML::Field->new('Radio', name => 'Flavors', options => [qw(Lemon Strawberry Grapefruit)], default => 'Grapefruit' ); # A single checkbox: my $checkbox = HTML::Field->new('Checkbox', name => 'Additional', option => 'Strawberry', default => 1, read_only_tags => { true => 'X', false => 'o'}); # Render editable HTML my ($key, $value) = $field->editable_html; # Render read-only value ($key, $value) = $field->readonly_html; # Render editable HTML for a new element ($key, $value) = $field->creation_html; # Set a field's value from a CGI object, hash reference or scalar: my $value = $field->value($cgi); # or, get the filed's value: $value = $field->value; # The 'read_only_tags' attribute sets the representation of a # check box or of radio buttons for a 'read only' rendering. # This feature can be used to load different images to represent # 'checked' radio buttons or check boxes. # Primary Key text field: my $field1 = HTML::Field->new('Textfield', name => 'login', size => 15, maxlength => 15, primary_key => 1 ); # When a text field is marked as 'primary' key, then # it will not be editable once it has a value. This means that if you # are displaying an empty form this will be an editable text field, # but if you are displaying a database record for edition, then this # field will not be editable and it will also be present as a hidden # field in order to get sent back to the script. # Primary key autogenerated by the database: my $serial = HTML::Field->new('Textfield', name => 'company_id', size => 4, maxlength => 4, auto => 1 ); # The same as above applies if the field value is generated by the # database. In that case, the value will never be editable; if the # field has no value then a place holder will be returned instead. DESCRIPTIONHTML::Field objects are able to read their values from CGI objects, hash references or plain scalars and then render those values as HTML fields or simple read-only HTML. They are meant to ease the interface between CGI, databases and templates.IMPORTANT NOTE: This module does not validate the values of any HTML attributes that you supply. See HTML::FieldForm for a class that works on sets of HTML::Fields. COMMON ATTRIBUTESCommon functional attributesThere are three functional attributes for all Field objects: "name", "value" and "default". By functional, I mean that these attributes have other uses than solely appearing in HTML. "value" and "default" have accessor/mutators named after them; "name" is read-only and must be set during creation."name" Of the three common, functional attributes only "name" is required. "name" will be used for the following important things:
So, if you are using HTML::Template, it is adviceable to name the parameters of your template the same as the fields you will use to populate it. "value" and "default" These two attributes define the value of the Field objects in different stages of their existance. If you include a "default" for an object, it will be the value that will be used since object creation until it is explicitly changed by "value". The "reset_value" method will set "value" equal to "default". You can feed "value" with a hash reference, a CGI object or a scalar value to set the value of a given field: $field->value($cgi); $field->value($hash_ref); $field->value(4); Common HTML AttributesSeveral HTML attributes can be used within all field tags. There are two kinds of HTML attributes: Those which can take a value and those which are just true or false. For those which can have a value, their value can be any scalar and it will simply be inculded in the field tag.All of these attributes may be set during object creation and also using their accessor/mutator (implemented via AUTOLOAD). The following HTML attributes may be used with all of the HTML::Field classes:
Each HTML::Field class may have its own, particular attributes. See below. COMMON METHODSBesides the accessor/mutator methods explained above, there are three methods common to every Field object:
ATTRIBUTES "primary_key" and "auto"If a form is displayed for the entry of a new record, then there are two scenarios regarding primary keys:
In summary, calling "creation_html" on a field marked as "primary_key" will display an editable field. Calling "editable_html" will return a read-only value followed with a hidden field. Calling "creation_html" on a field marked as "auto" will only display an HTML comment as a marker. Calling "editable_html" will display a hidden field instead, and in the case of a text field, it will also display its value. You can only mark text fields as 'primary_key'; text and hidden fields support 'auto'. SUBCLASSES AND THEIR PARTICULAR ATTRIBUTES AND METHODSHTML::Field::TextfieldATTRIBUTESThese attributes are optional. They have accessor/mutator methods (via AUTOLOAD).
HTML::Field::HiddenFields of this class must have a value when issueing editable HTML or they will raise an exception.These fields may be marked as "auto", but not as "primary_key".
HTML::Field::PasswordATTRIBUTESThese attributes are optional. They have accessor/mutator methods (via AUTOLOAD).
HTML::Field::TextareaATTRIBUTESThese attributes are optional. They have accessor/mutator methods (via AUTOLOAD).
HTML::Field::CheckboxThis class is useful to implement single checkboxes; in other words, checkboxes that have their own name.ATTRIBUTES These attributes are optional. They have accessor/mutator methods (via AUTOLOAD).
HTML::Field::SelectATTRIBUTESThese attributes have accessor/mutator methods (via AUTOLOAD).
HTML::Field::RadioClass to create radio button fields. A single object will generate as many radio buttons as options it has. These buttons will be named like this:field_option So, following the example in the synopsis, we would have: Flavors_Lemon, Flavors_Strawberry, and Flavors_Grapefruit. ATTRIBUTES These attributes have accessor/mutator methods (via AUTOLOAD).
SEE ALSOHTML::FieldForm is a module that manages sets of HTML::Field objects.AUTHORJulio Fraire, <julio.fraire@gmail.com<gt>COPYRIGHT AND LICENSECopyright (C) 2009 by Julio FraireThis library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.
|