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

FreeBSD Manual Pages

  
 
  

home | help
HTML::FormFu::Element:UsereContributed PerHTML::FormFu::Element::Repeatable(3)

NAME
       HTML::FormFu::Element::Repeatable - repeatable block element

VERSION
       version 2.05

SYNOPSIS
	   ---
	   elements:
	     - type: Repeatable
	       name: my_rep
	       elements:
		 - name: foo
		 - name: bar

       Calling "$element->repeat(2)" would result in the following markup:

	   <div>
	       <input name="my_rep.foo_1" type="text" />
	       <input name="my_rep.bar_1" type="text" />
	   </div>
	   <div>
	       <input name="my_rep.foo_2" type="text" />
	       <input name="my_rep.bar_2" type="text" />
	   </div>

       Example of constraints:

	   ----
	   elements:
	     - type: Repeatable
	       name: my_rep
	       elements:
		 - name: id

		 - name: foo
		   constraints:
		     - type: Required
		       when:
			 field:	'my_rep.id' # use full nested-name

		 - name: bar
		   constraints:
		     - type: Equal
		       others: 'my_rep.foo' # use full nested-name

DESCRIPTION
       Provides	a way to extend	a form at run-time, by copying and repeating
       its child elements.

       The elements intended for copying must be added before "repeat" is
       called.

       Although	the Repeatable element inherits	from Block, it doesn't
       generate	a block	tag around all the repeated elements - instead it
       places each repeat of the elements in a new Block element, which
       inherits	the Repeatable's display settings, such	as "attributes"	and
       "tag".

       For all constraints attached to fields within a Repeatable block	which
       use either others or when containing names of fields within the same
       Repeatable block, when repeat is	called,	those names will automatically
       be updated to the new nested-name for each field	(taking	into account
       increment_field_names).

METHODS
   repeat
       Arguments: [$count]

       Return Value: $arrayref_of_new_child_blocks

       This method creates $count number of copies of the child	elements.  If
       no argument $count is provided, it defaults to 1.

       Note that "$form->process" will call "repeat" automatically to ensure
       the initial child elements are correctly	set up - unless	you call
       "repeat"	manually first,	in which case the child	elements you created
       will be left untouched (otherwise process would overwrite your
       changes).

       Any subsequent call to "repeat" will delete the previously copied
       elements	before creating	new copies - this means	you cannot make
       repeated	calls to "repeat" within a loop	to create more copies.

       Each copy of the	elements returned are contained	in a new Block
       element.	For example, calling "$element->repeat(2)" on a	Repeatable
       element containing 2 Text fields	would return 2 Block elements, each
       containing a copy of the	2 Text fields.

   counter_name
       Arguments: $name

       If true,	the "query" in HTML::FormFu will be searched during "process"
       in HTML::FormFu for a parameter with the	given name. The	value for that
       parameter will be passed	to "repeat", to	automatically create the new
       copies.

       If "increment_field_names" is true (the default), this is essential: if
       the elements corresponding to the new fieldnames	(foo_1,	bar_2, etc.)
       are not present on the form during "process" in HTML::FormFu, no
       Processors (Constraints,	etc.) will be run on the fields, and their
       values will not be returned by "params" in HTML::FormFu or "param" in
       HTML::FormFu.

   increment_field_names
       Arguments: $bool

       Default Value: 1

       If true,	then all fields	will have "_n" appended	to their name, where
       "n" is the "repeatable_count" value.

   repeatable_count
       This is set on each new Block element returned by "repeat", starting at
       number 1.

       Because this is an 'inherited accessor' available on all	elements, it
       can be used to determine	whether	any element is a child of a Repeatable
       element.

       Only available after repeat has been called.

   repeatable_count_no_inherit
       A non-inheriting	variant	of "repeatable_count".

   nested_name
       If the "nested_name" attribute is set, the naming scheme	of the
       Repeatable element's children is	switched to add	the counter to the
       repeatable blocks themselves.

	   ---
	   elements:
	     - type: Repeatable
	       nested_name: my_rep
	       elements:
		 - name: foo
		 - name: bar

       Calling "$element->repeat(2)" would result in the following markup:

	   <div>
	       <input name="my_rep_1.foo" type="text" />
	       <input name="my_rep_1.bar" type="text" />
	   </div>
	   <div>
	       <input name="my_rep_2.foo" type="text" />
	       <input name="my_rep_2.bar" type="text" />
	   </div>

       Because this is an 'inherited accessor' available on all	elements, it
       can be used to determine	whether	any element is a child of a Repeatable
       element.

   attributes
   attrs
       Any attributes set will be passed to every repeated Block of elements.

	   ---
	   elements:
	     - type: Repeatable
	       name: my_rep
	       attributes:
		 class:	rep
	       elements:
		 - name: foo

       Calling "$element->repeat(2)" would result in the following markup:

	   <div	class="rep">
	       <input name="my_rep.foo_1" type="text" />
	   </div>
	   <div	class="rep">
	       <input name="my_rep.foo_2" type="text" />
	   </div>

       See "attributes"	in HTML::FormFu	for details.

   tag
       The "tag" value will be passed to every repeated	Block of elements.

	   ---
	   elements:
	     - type: Repeatable
	       name: my_rep
	       tag: span
	       elements:
		 - name: foo

       Calling "$element->repeat(2)" would result in the following markup:

	   <span>
	       <input name="my_rep.foo_1" type="text" />
	   </span>
	   <span>
	       <input name="my_rep.foo_2" type="text" />
	   </span>

       See "tag" in HTML::FormFu::Element::Block for details.

   auto_id
       As well as the usual substitutions, any instances of %r will be
       replaced	with the value of "repeatable_count".

       See "auto_id" in	HTML::FormFu::Element::Block for further details.

	   ---
	   elements:
	     - type: Repeatable
	       name: my_rep
	       auto_id:	"%n_%r"
	       elements:
		 - name: foo

       Calling "$element->repeat(2)" would result in the following markup:

	   <div>
	       <input name="my_rep.foo_1" id="foo_1" type="text" />
	   </div>
	   <div>
	       <input name="my_rep.foo_2" id="foo_2" type="text" />
	   </div>

   content
       Not supported for Repeatable elements - will throw a fatal error	if
       called as a setter.

CAVEATS
   Unsupported Constraints
       Note that constraints with an others method do not work correctly
       within a	Repeatable block. Currently, these are:	AllOrNone, DependOn,
       Equal, MinMaxFields, reCAPTCHA.	Also, the CallbackOnce constraint
       won't work within a Repeatable block, as	it wouldn't make much sense.

   Work-arounds
       See HTML::FormFu::Filter::ForceListValue	to address a problem with
       increment_field_names disabled, and increading the repeat on the
       server-side.

SEE ALSO
       Is a sub-class of, and inherits methods from
       HTML::FormFu::Element::Block, HTML::FormFu::Element

       HTML::FormFu

AUTHOR
       Carl Franks, "cfranks@cpan.org"

LICENSE
       This library is free software, you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.24.1			  2016-10-HTML::FormFu::Element::Repeatable(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | CAVEATS | SEE ALSO | AUTHOR | LICENSE

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

home | help