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

FreeBSD Manual Pages

  
 
  

home | help
HTML::FormHandler::FieUserRContributed)HTML::FormHandler::Field::Repeatable(3)

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

VERSION
       version 0.40067

SYNOPSIS
       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 'addresses.city';
	 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 ('addresses.city');

       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'] } },
	   );

DESCRIPTION
       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:

	  $form->field('tags')->field('0')
	  $form->field('addresses')->field('0')->field('city')

       or using	the shortcut form:

	  $form->field('tags.0')
	  $form->field('addresses.0.city')

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

	  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.

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

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

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

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

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

       add_extra
	   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 => {....}	);
	       $form->field('my_repeatable')->add_extra(1);

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

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

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-HTML::FormHandler::Field::Repeatable(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | ATTRIBUTES | AUTHOR | COPYRIGHT AND LICENSE

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

home | help