Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTML::Field(3)	      User Contributed Perl Documentation	HTML::Field(3)

NAME
       HTML::Field - Generation	of HTML	form elements

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
       HTML::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 ATTRIBUTES
   Common functional attributes
       There 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:

       1. To look for the field	value in a hash	or a CGI object
       2. As the key in	the hashes returned by the html	methods
       3. As the name of the html tags produced

       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 Attributes
       Several 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:

       accesskey
       id
       title
       class
       style
       lang
       dir
       tabindex
       disabled	(Boolean)
       readonly	(Boolean)

       Each HTML::Field	class may have its own,	particular attributes. See
       below.

COMMON METHODS
       Besides the accessor/mutator methods explained above, there are three
       methods common to every Field object:

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

   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:

       "auto" -- Primary key is	generated by the database or application
	   In this case	the system generates a value for the primary key prior
	   to its insertion in the database. This value	will not exist when
	   the empty form is served to the client for the first	time, so it
	   should not be included. However, it will exist and is needed	if the
	   record is requested for updating. In	this case it will be sent in a
	   non-editable	form, followed by a hidden field (in the case of text
	   fields). Think of using a hidden field for this case.

       "primary_key" --	Primary	key is entered by the user
	   If the primary key of a record will be supplied by the user,	then
	   the field must be empty and editable	when the form is first
	   displayed. Once the record exists the primary key will be sent in a
	   read-only form followed by a	hidden	field. This way	the primary
	   key will be present in the data sent	back to	the server for
	   updating the	database.

	   Note	that because the field needs to	be editable for	record
	   creation, a hidden field cannot be marked as	primary	key.

       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 METHODS
   HTML::Field::Textfield
       ATTRIBUTES

       These attributes	are optional. They have	accessor/mutator methods (via
       AUTOLOAD).

       size
       maxlength
       primary_key (Not	an HTML	attribute; see explanation above)
       auto (Not an HTML attribute; see	explanation above)

   HTML::Field::Hidden
       Fields 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".

       auto (Not an HTML attribute; see	explanation above)

   HTML::Field::Password
       ATTRIBUTES

       These attributes	are optional. They have	accessor/mutator methods (via
       AUTOLOAD).

       size
       maxlength

   HTML::Field::Textarea
       ATTRIBUTES

       These attributes	are optional. They have	accessor/mutator methods (via
       AUTOLOAD).

       cols
       rows
       wrap

   HTML::Field::Checkbox
       This 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).

       readonly_tags
	   This	attribute can take a hash with the keys	'true' and 'false',
	   which should	point to read-only representations of checked (true)
	   or not checked (false) fields. For example:

	    $field->readonly_tags(
		   true	 => '<img src="checked.png"	alt="Checked"/>',
		   false => '<img src="not_checked.png"	alt="Not checked"/>',
	    );

	   Default is '+' for true and '-' for false.

   HTML::Field::Select
       ATTRIBUTES

       These attributes	have accessor/mutator methods (via AUTOLOAD).

       size -- Optional
       multiple	-- Optional (true or false only)
       options -- Required
	   Array reference of options.

       labels -- Required
	   "labels" will accept	a hash of labels keyed by option.

   HTML::Field::Radio
       Class 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).

       options -- Required
	   Array reference of options.

       readonly_tags
	   See HTML::Field::Checkbox for an explanation.

SEE ALSO
       HTML::FieldForm is a module that	manages	sets of	HTML::Field objects.

AUTHOR
       Julio Fraire, <julio.fraire@gmail.com<gt>

COPYRIGHT AND LICENSE
       Copyright (C) 2009 by Julio Fraire

       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.

perl v5.32.1			  2009-11-26			HTML::Field(3)

NAME | SYNOPSIS | DESCRIPTION | COMMON ATTRIBUTES | COMMON METHODS | SUBCLASSES AND THEIR PARTICULAR ATTRIBUTES AND METHODS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::Field&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help