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

FreeBSD Manual Pages

  
 
  

home | help
HTML::FormHandler::ManUser:Contributed PerHTML::FormHandler::Manual::Fields(3)

NAME
       HTML::FormHandler::Manual::Fields - brief documentation of available
       fields

VERSION
       version 0.40067

SYNOPSIS
       Manual Index

       See also	HTML::FormHandler::Field for a description of the base field
       attributes.

       The inheritance hierarchy of HTML::FormHandler Fields

	  Text
	     Money
	     Password
	     Hidden
	     Integer
		PosInteger
	     Float
	     Date
		DateMDY
	     Email
	     TextCSV
	  TextArea
	  Select
	     Multiple
	     SelectCSV
	     BoolSelect
	     IntRange
		Hour
		Minute
		MonthDay
		Month
		Second
		Year
	     MonthName
	     Weekday
	  Checkbox
	     Boolean
	  Compound
	     Repeatable
	     Duration
	     DateTime
	  NoValue
	     Submit
	     Reset
	     Button
	     Display
	     AddElement
	     RmElement
	     NonEditable
	  PrimaryKey
	  Upload
	  File

DESCRIPTION
       A form's	fields are created from	the 'has_field'	and 'field_list'
       definitions.  FormHandler processes the field lists and creates an
       array of	HTML::FormHandler::Field objects. The "type" of	a field
       determines which	field class to use. The	field class determines which
       attributes are valid for	a particular field. A number of	field classes
       are provided by FormHandler. You	can customize the validation in	your
       form on a per field basis, but validation that will be used for more
       than one	field might be more easily handled in a	custom field class.

       Fields are accessed with	"form->field('name')".	Field errors are in
       "$field->errors".

       If the 'field_name_space' is not	set, fields will be loaded from	the
       HTML::FormHandler::Field	name space. If you provide a
       'field_name_space' it will be searched before FormHandler. If you want
       to explicitly list the field's package, prefix it with a	plus sign. The
       field_name_space	plus the default name spaces
       'HTML::FormHandler::Field' and 'HTML::FormHandlerX::Field' will be
       searched	for fields.

	   has '+field_name_space' => (	default	=> 'MyApp::Form::Field'	);
	   has_field 'name' => ( type => 'Text'	); # HTML::FormHandler::Field::Text
	   has_field 'name' => ( type => '+My::FieldType' ); # My::Fieldtype
	   has_field 'foo'  => ( type => '+Foo'	);  # MyApp::Form::Field::Foo
	     or
	   has_field 'foo'  => ( type => 'Foo' );  # MyApp::Form::Field::Foo

       The most	basic type is "Text", which is usually a 'text'	HTML element
       and a string data type. (If the type of a field is not specified, it
       will be set to 'Text'.)	A "Select" field type is a HTML	select
       element,	and validates against the list of values provided in the
       'options'. A "Multiple" type is like "Select" but it allows selecting
       more than one value at a	time.

       Many field classes contain only a list of constraints and
       transformations to apply. Some use the 'validate' method, which is
       called after the	actions	are applied. Some build	a custom select	list
       using 'build_options'.

       There are two rough categories of Field classes:	those that do extra
       processing and those that are simple validators.	The 'Compound',
       'Repeatable', and 'Select' fields are fields that are functional.

Field names
       The standard way	to use FormHandler is with field names that match your
       database	accessors. If you want to prepend the HTML field names with a
       name plus dot, you can set the form 'name' and use the 'html_prefix'
       flag. "$name." will be stripped from the	beginning of the HTML fields
       before processing by HFH, and will be added back	in 'fif'. The field's
       'html_name' convenience attribute will return this name for use in
       templates.

       If you want the FormHandler field name to be different than the
       database	accessor, set 'accessor' on your fields. (It defaults to the
       field name.) You	could then use any name	that you want for your field.

       There are a number of name-related field	attributes. The	'name' is the
       name used to identify this particular field in this fields array.  The
       'full_name' includes the	names of all parents of	this field, like
       'address.street.streetname'. The	'html_name' is the same	as the
       'full_name' unless you have set the 'html_prefix' flag, in which	case
       it includes the form name: 'myform.address.street.streetname'.

       To retrieve a field by name, you	can use	either the full_name or	a
       chain: "$form->field('address')->field('street')->field('streetname')"
       or: "$form->field('address.street.streetname')".

Creating custom	fields
       Subclass	a custom field from HTML::FormHandler::Field, or one of	the
       existing	subclasses. Almost everything that is done in a	custom field
       class can also be done in a form. The advantage of a field class	is
       that it can simplify declaration	of often-repeated sets of attributes.

       The simplest subclasses contain only a 'validate' routine or an 'apply'
       attribute, which	is called by the base Field class from 'process'. Look
       at HTML::FormHandler::Field::Email, for example.

       If the field's value will be an object instead of a simple scalar, such
       as a DateTime, and you want to use the transformed value	to fill	in the
       form, then you will also	need a deflation or field class	'deflate'
       method to reformat the object into a form suitable for an HTML form
       field.  See HTML::FormHandler::Manual::InflationDeflation for more
       info.

       Some custom fields might	only require setting certain attributes	to
       defaults, such as the HTML::FormHandler::Field::Hour field, which set
       'range_start' to	0 and 'range_end' to 23. A 'select' field might
       override	the 'build_options' builder for	the 'options' array, like
       HTML::FormHandler::Field::IntRange. A field may add additional
       attributes, such	as 'label_format' in
       HTML::FormHandler::Field::IntRange, or set the 'required' message.

       An alternative to new field classes for many field validations might be
       roles with collections of validations.

Other field packages
       Some custom fields are supplied as CPAN packages, in the
       HTML::FormHandlerX name space.

       reCAPTCHA

       DateTimeNatural

       URI::HTTP

Fields supplied	by FormHandler
   Basic Fields
       Although	there are a lot	of fields provided (probably too many) a lot
       of them are "convenience" fields	or "name" fields, where	the main
       benefit is that the field type is a name	that gives the main purpose of
       the field.  Most	of these fields	could be replaced by a basic field
       with a bit of validation	or some	select options.	A few of the fields
       are special purpose fields that won't be	used very often.

       The fields in this section are the basic	fields,	the commonly used
       fields that will	be most	often used in a	form.

       Text

       A string	data type that will be formatted as an HTML text field.	Has
       'minlength' and 'maxlength' attributes.

       HTML::FormHandler::Field::Text

       Select

       A field formatted as a select element.

       HTML::FormHandler::Field::Select

       Checkbox

       A field formatted as a checkbox.	If not in params, will be forced to
       'false' value by	'input_without_param' attribute	(0 by default).

       HTML::FormHandler::Field::Checkbox

       Hidden

       A hidden	field.

       HTML::FormHandler::Field::Hidden

       Password

       A password field. The value is not re-displayed.

       HTML::FormHandler::Field::Password

       TextArea

       A textarea field.  Has 'cols' and 'rows'	attributes.

       HTML::FormHandler::Field::TextArea

       Upload

       A file upload field that	takes a	filehandle or a	Catalyst upload	object
       (an object with a 'size'	method).

       HTML::FormHandler::Field::Upload

       Submit

       A submit	field.

       HTML::FormHandler::Field::Submit

       Reset

       A reset field.

       HTML::FormHandler::Field::Reset

   Complex Fields (Compound and	Repeatable)
       These fields are	complex	fields which contain a fair amount of special
       code. They do not map to	a single HTML element; they contain multiple
       subfields.

       Compound

       A compound field	is a field that	has sub-fields.	Compound fields	can be
       created in two ways: 1) using a field class, 2) by declaration.

       To create a compound field class, you must extend
       HTML::FormHandler::Field::Compound and use HTML::FormHandler::Moose to
       allow declaring fields:

	 package MyApp::Field::Duration;

	 use HTML::FormHandler::Moose;
	 extends 'HTML::FormHandler::Field::Compound';

	 has_field 'month' => (type => 'Integer');
	 has_field 'day' => ( type => 'Integer'	);
	 has_field 'minutes' =>	( type => 'Integer' );

       Then in the form:

	 has_field 'my_duration' => ( type => '+Duration' );

       To create a compound field by declaration, declare the containing
       compound	field and subfields, prefixing the subfield names with the
       name of the containing compound field plus a dot:

	  package MyApp::Form;

	  use HTML::FormHandler::Moose;
	  extends 'HTML::FormHandler';

	  has_field 'duration' => ( type => 'Compound' );
	  has_field 'duration.month' =>	( type => 'Integer' );
	  has_field 'duration.day' => (	type =>	'Integer' );
	  has_field 'duration.year' => ( type => 'Integer' );

       In an HTML form the name	of the field must be the complete name with
       dots. The 'html_name' field attribute can be used to get	this name,
       "$field->html_name".

       A compound field	can be used for	a database relation that will have
       only one	row (belongs_to	or has_one). If	the relation has a compound
       primary key, you	may need to provide the	primary	key columns, either
       through hidden fields or	by setting them	in the "$form->value" hash
       before 'update_model' is	called.

       See also	HTML::FormHandler::Field::Compound.

       Repeatable

       Repeatable fields are used for arrays of	compound fields.

	  has_field 'addresses'	=> ( type => 'Repeatable' );
	  has_field 'addresses.address_id' => (	type =>	'PrimaryKey' );
	  has_field 'addresses.street';
	  has_field 'addresses.city';
	  has_field 'addresses.country'	=> ( type => 'Select' );

       The arrays will be built	from arrays passed in the params, or from
       related ('has_many') rows in the	database.

       It is also used for arrays of single fields using the 'contains'
       keyword:

	 has_field 'tags' => ( type => 'Repeatable' );
	 has_field 'tags.contains' => (	type =>	'+Tag' );

       See HTML::FormHandler::Field::Repeatable	for more information.

   Text	Fields
       Fields subclassed from the Text field.

       Text

       Text field.

       HTML::FormHandler::Field::Text

       Money

       Positive	or negative real value,	formatted to two decimal places.

       HTML::FormHandler::Field::Money

       Date

       Date field that can be used by jQuery datepicker	plugin.

       HTML::FormHandler::Field::Date

       DateMDY

       A subclass of 'Date' with the "%m/%d/%Y"	format.

       HTML::FormHandler::Field::DateMDY

       Email

       Uses Email::Valid for validation.

       HTML::FormHandler::Field::Email

       Integer

       Positive	and negative integers. Can use range_start and range_end.

       HTML::FormHandler::Field::Integer

       PosInteger

       A positive integer field.

       HTML::FormHandler::Field::PosInteger

       Float

       Float field that	allows you to set size,	precision, decimal_symbol, and
       decimal_symbol_for_db.

       HTML::FormHandler::Field::Float

       TextCSV

       A text field that takes multiple	values from a database and converts
       them to comma-separated values. This is intended	for javascript fields
       that require that, such as 'select2'. This is the only 'multiple' text
       field. This text	field would be a select-type field for the user.

       HTML::FormHandler::Field::TextCSV

   Compound Fields
       Fields subclassed from 'Compound'.

       Compound

       HTML::FormHandler::Field::Compound

       Repeatable

       HTML::FormHandler::Field::Repeatable

       Duration

       Compound	field with possible subfields: years, months, weeks, days,
       hours, minutes, seconds,	nanoseconds.

       HTML::FormHandler::Field::Duration

       DateTime

       A compound field	that requires you to provide the subfields that	you
       want. (month/day/year/hour/minutes)

       HTML::FormHandler::Field::DateTime

   Checkbox Fields
       Fields that inherit from	'Checkbox'.

       Checkbox

       HTML::FormHandler::Field::Checkbox

       Boolean

       Checkbox	that return 1 or 0.

       HTML::FormHandler::Field::Boolean

   Select Fields
       Fields that inherit from	'Select'.

       Select

       HTML::FormHandler::Field::Select

       Multiple

       Multiple	select.	Also sorts the selected	options	to the top of the
       select list.

       HTML::FormHandler::Field::Multiple

   SelectCSV
       A multiple select field for comma-separated values in the database.  It
       expects database	values like: '1,5,7'. The string will be inflated into
       an arrayref for validation and form filling, and	will be	deflated into
       a comma-separated string	in the output value.

       HTML::FormHandler::Field::SelectCSV

       BoolSelect

       A field with three possible values: empty/0/1.

       HTML::FormHandler::Field::BoolSelect

       Hour

       Integer select range field from 0-23.

       HTML::FormHandler::Field::Hour

       Second

       Select field with range from 0-59.

       HTML::FormHandler::Field::Second

       IntRange

       An integer select field.	Can set	label format with 'label_format'.

       HTML::FormHandler::Field::IntRange

       Month

       Select field with range from 1 -	12.

       HTML::FormHandler::Field::Month

       MonthDay

       Select field with range from 1 -	31.

       HTML::FormHandler::Field::MonthDay

       MonthName

       Select field with month name labels, value 1-12.

       HTML::FormHandler::Field::MonthName

       Minute

       Select field with range from 0-59.

       HTML::FormHandler::Field::Minute

       Weekday

       A select	field where the	labels are the names of	the week, and the
       values are 0-6.

       HTML::FormHandler::Field::Weekday

       Year

       Select field providing year list	5 years	back and 10 years forward.

       HTML::FormHandler::Field::Year

   NoValue fields
       Fields that inherit from	'NoValue'. None	of these fields	will provide a
       'value' in the "$form->value" hashref.

       NoValue

       Base class for fields that don't	produce	a 'value'.

       HTML::FormHandler::Field::NoValue

       Submit

       HTML::FormHandler::Field::Submit

       Reset

       HTML::FormHandler::Field::Reset

       Button

       Button field that is rendered by	the Button widget.

       HTML::FormHandler::Field::Button

       Display

       Non-data	field used for inserting HTML into the form. Probably now
       better handled by a Block or a rendering	tag.

       HTML::FormHandler::Field::Display

       AddElement

       Example field for adding	a repeatable element.

       HTML::FormHandler::Field::AddElement

       RmElement

       Example field for removing a repeatable element

       HTML::FormHandler::Field::RmElement

       NonEditable

       For Bootstrap-style non-editable	fields.

   TextArea fields
       Fields that inherit from	'TextArea'.

       TextArea

       HTML::FormHandler::Field::TextArea

   Password fields
       Password

       Password	field. Sets 'noupdate' flag if empty and not required.

       HTML::FormHandler::Field::Password

       PasswordConf

       Password	confirmation field.

       HTML::FormHandler::Field::PasswordConf

   Other fields
       These fields inherit just from 'Field'.

       File

       A file field that does no processing. Most people probably want to use
       'Upload'	instead.

       HTML::FormHandler::Field::File

       PrimaryKey

       Hidden field that provides the primary key for Repeatable fields.

       HTML::FormHandler::Field::PrimaryKey

       Captcha

       A Captcha field using GD::SecurityImage.	Requires the use of the
       HTML::FormHandler::TraitFor::Captcha role, or similar code.

       HTML::FormHandler::Field::Captcha

AUTHOR
       FormHandler Contributors	- see HTML::FormHandler

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2016 by Gerda Shank.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.24.1			  2016-10-HTML::FormHandler::Manual::Fields(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | Field names | Creating custom fields | Other field packages | Fields supplied by FormHandler | AUTHOR | COPYRIGHT AND LICENSE

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

home | help