NAME

SYNOPSIS

 use 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.

DESCRIPTION

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 ATTRIBUTES

 $field->value($cgi);
 $field->value($hash_ref);
 $field->value(4);

COMMON METHODS

$field->reset_values

Makes "value" equal to "default".

%hash = $field->editable_html

The returned hash will have the field's name as key and its HTML field tag as value. It returns a hash because this way it is simpler to include it in a template (think HTML::Template). In this case, you can use it like this:

 $template->param($field->editable_html);
    

%hash = $field->readonly_html

Same as above, except that the HTML will not be a form tag but only a read-only HTML representation of the field's value. Usually this read-only HTML is simply the value of the field.

For the checkboxes and radio buttons, it is possible to have images or any other mark up to display 'true' and 'false' states for reading via the "readonly_tags" attribute; you can see it in the SYNOPSIS. This attribute has its accessor/mutator of the same name.

%hash = $field->creation_html

This method will return an empty HTML field for edition. Normally this method should be used when creating a new record in a database, as it will allow for the edition of fields marked as 'primary_key' (not for 'auto'). See the next section for an extended explanation.

SUBCLASSES AND THEIR PARTICULAR ATTRIBUTES AND METHODS

 field_option

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

This 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.