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

FreeBSD Manual Pages


home | help

       HTML::FormHandler::Field::Repeatable - repeatable (array) field

       version 0.40068

       In a form, for an array of hashrefs, equivalent to a 'has_many'
       database	relationship.

	 has_field 'addresses' => ( type => 'Repeatable' );
	 has_field 'addresses.address_id' => ( type => 'PrimaryKey' );
	 has_field 'addresses.street';
	 has_field '';
	 has_field 'addresses.state';

       In a form, for an array of single fields	(not directly equivalent to a
       database	relationship) use the 'contains' pseudo	field name:

	 has_field 'tags' => ( type => 'Repeatable' );
	 has_field 'tags.contains' => (	type =>	'Text',
	      apply => [ { check => ['perl', 'programming', 'linux', 'internet'],
			   message => 'Not a valid tag'	} ]

       or use 'contains' with single fields which are compound fields:

	 has_field 'addresses' => ( type => 'Repeatable' );
	 has_field 'addresses.contains'	=> ( type => '+MyAddress' );

       If the MyAddress	field contains fields 'address_id', 'street', 'city',
       and 'state', then this syntax is	functionally equivalent	to the first
       method where the	fields are declared with dots ('');

       You can pass attributes to the 'contains' field by supplying an
       'init_contains' hashref.

	   has_field 'addresses' => ( type => 'Repeatable,
	      init_contains => { wrapper_attr => { class => ['hfh', 'repinst'] } },

       This class represents an	array. It can either be	an array of hashrefs
       (compound fields) or an array of	single fields.

       The 'contains' keyword is used for elements that	do not have names
       because they are	not hash elements.

       This field node will build arrays of fields from	the parameters or an
       initial object, or empty	fields for an empty form.

       The name	of the element fields will be an array index, starting with 0.
       Therefore the first array element can be	accessed with:


       or using	the shortcut form:


       The array of elements will be in	"$form->field('addresses')->fields".
       The subfields of	the elements will be in	a fields array in each

	  foreach my $element (	$form->field('addresses')->fields )
	     foreach my	$field ( $element->fields )
		# do something

       Every field that	has a 'fields' array will also have an 'error_fields'
       array containing	references to the fields that contain errors.

       When new	elements are created by	a Repeatable field in a	database form
       an attempt is made to re-load the Repeatable field from the database,
       because otherwise the repeatable	elements will not have primary keys.
       Although	this works, if you have	included other fields in your
       repeatable elements that	do *not* come from the database, the
       defaults/values must be able to be loaded in a way that works when the
       form is initialized from	the database item. This	is only	an issue if
       you re-present the form after the database update succeeds.

	   This	attribute contains the next index number available to create
	   an additional array element.

	   When	the Repeatable is repeated, this hashref will be used to
	   initialise each instance. It	can contain any	of the same attributes
	   you would normally give to "has_field" in HTML::FormHandler,	except
	   "type", for obvious reasons.

	       has_field 'addresses' =>	(
		   type	=> 'Repeatable',
		   init_contains => {
		       wrapper_attr => {
			   rel => 'address'
		       wrapper_class =>	[ 'row'	]

	   Note	that providing a "wrapper_class" to this hashref will override
	   the default "hfh-repinst" class on these instances.

	   This	attribute (default 1) indicates	how many empty fields to
	   present in an empty form which hasn't been filled from parameters
	   or database rows.

	   When	the field results are built from an existing object (item or
	   init_object)	an additional number of	repeatable elements will be
	   created equal to this number. Default is 0.

	   When	a form is submitted and	the field results are built from the
	   input parameters, it's not clear when or if an additional
	   repeatable element might be wanted. The method 'add_extra' will add
	   an empty repeatable element.

	       $form->process( params => {....}	);

	   This	might be useful	if the form is being re-presented to the user.

	       setup_for_js => 1

	   Saves information in	the form for javascript	to use when adding
	   repeatable elements.	 If using the example javascript, you also
	   must	set 'do_wrapper' in the	Repeatable field and use the Bootstrap
	   widget wrapper (or wrap the repeatable elements in a	'controls' div
	   by setting tags => {	controls_div =>	1 }.  See t/repeatable/js.t
	   for an example. See also HTML::FormHandler::Render::RepeatableJs
	   and HTML::FormHandler::Field::AddElement.

       FormHandler Contributors	- see HTML::FormHandler

       This software is	copyright (c) 2017 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.32.0			  2017-HTML::FormHandler::Field::Repeatable(3)


Want to link to this manual page? Use this URL:

home | help