Class: HTML_QuickForm2_Container_Repeat

Source Location: /HTML_QuickForm2-2.1.0/HTML/QuickForm2/Container/Repeat.php

Class Overview

HTML_Common2
   |
   --HTML_QuickForm2_Node
      |
      --HTML_QuickForm2_Container
         |
         --HTML_QuickForm2_Container_Repeat

Handles a Container that can be repeated multiple times in the form

Author(s):

Bertrand Mansion <golgote at mamasam.com>
Alexey Borzov <avb at php.net>

Version:

Release: 2.1.0

Inherited Variables

Class: HTML_QuickForm2_Container

HTML_QuickForm2_Container::$elements

Class: HTML_QuickForm2_Node

HTML_QuickForm2_Node::$container
HTML_QuickForm2_Node::$data
HTML_QuickForm2_Node::$error
HTML_QuickForm2_Node::$filters
HTML_QuickForm2_Node::$frozen
HTML_QuickForm2_Node::$ids
HTML_QuickForm2_Node::$persistent
HTML_QuickForm2_Node::$recursiveFilters
HTML_QuickForm2_Node::$rules
HTML_QuickForm2_Node::$watchedAttributes

Inherited Methods

Class: HTML_QuickForm2_Container

HTML_QuickForm2_Container::addElement(): Appends an element to the container (possibly creating it first)
HTML_QuickForm2_Container::appendChild(): Appends an element to the container
HTML_QuickForm2_Container::arrayMerge(): Merges two arrays
HTML_QuickForm2_Container::count(): Returns the number of elements in the container
HTML_QuickForm2_Container::getChildValues(): Returns the array containing child elements' values
HTML_QuickForm2_Container::getElementById(): Returns an element if its id is found
HTML_QuickForm2_Container::getElements(): Returns an array of this container's elements
HTML_QuickForm2_Container::getElementsByName(): Returns an array of elements which name corresponds to element
HTML_QuickForm2_Container::getIterator(): Returns a recursive iterator for the container elements
HTML_QuickForm2_Container::getJavascriptTriggers()
HTML_QuickForm2_Container::getJavascriptValue(): Returns Javascript code for getting the element's value
HTML_QuickForm2_Container::getRawValue(): Returns the container's value without filters applied
HTML_QuickForm2_Container::getRecursiveIterator(): Returns a recursive iterator iterator for the container elements
HTML_QuickForm2_Container::getValue(): Returns the container's value, possibly with filters applied
HTML_QuickForm2_Container::insertBefore(): Inserts an element in the container
HTML_QuickForm2_Container::persistentFreeze()
HTML_QuickForm2_Container::prependsName(): Whether container prepends its name to names of contained elements
HTML_QuickForm2_Container::removeChild(): Removes the element from this container
HTML_QuickForm2_Container::render(): Renders the container using the given renderer
HTML_QuickForm2_Container::setName()
HTML_QuickForm2_Container::toggleFrozen()
HTML_QuickForm2_Container::updateValue(): Called when the element needs to update its value from form's data sources
HTML_QuickForm2_Container::validate(): Performs the server-side validation
HTML_QuickForm2_Container::__call(): Appends an element to the container, creating it first
HTML_QuickForm2_Container::__toString()

Class: HTML_QuickForm2_Node

HTML_QuickForm2_Node::__construct(): Class constructor
HTML_QuickForm2_Node::addFilter(): Adds a filter
HTML_QuickForm2_Node::addRecursiveFilter(): Adds a recursive filter
HTML_QuickForm2_Node::addRule(): Adds a validation rule
HTML_QuickForm2_Node::applyFilter(): Helper function for applying filter callback to a value
HTML_QuickForm2_Node::applyFilters(): Applies non-recursive filters on element value
HTML_QuickForm2_Node::createRule(): Creates a validation rule
HTML_QuickForm2_Node::generateId(): Generates an id for the element
HTML_QuickForm2_Node::getContainer(): Returns the element containing current
HTML_QuickForm2_Node::getData(): Returns the element options
HTML_QuickForm2_Node::getDataSources(): Returns the data sources for this element
HTML_QuickForm2_Node::getError(): Returns the error message for the element
HTML_QuickForm2_Node::getId(): Returns the element's id
HTML_QuickForm2_Node::getJavascriptTriggers(): Returns IDs of form fields that should trigger "live" Javascript validation
HTML_QuickForm2_Node::getJavascriptValue(): Returns Javascript code for getting the element's value
HTML_QuickForm2_Node::getLabel(): Returns the element's label(s)
HTML_QuickForm2_Node::getName(): Returns the element's name
HTML_QuickForm2_Node::getRawValue(): Returns the element's value without filters applied
HTML_QuickForm2_Node::getType(): Returns the element's type
HTML_QuickForm2_Node::getValue(): Returns the element's value, possibly with filters applied
HTML_QuickForm2_Node::isRequired(): Checks whether an element is required
HTML_QuickForm2_Node::onAttributeChange(): Intercepts setting 'name' and 'id' attributes
HTML_QuickForm2_Node::persistentFreeze(): Changes the element's persistent freeze behaviour
HTML_QuickForm2_Node::removeRule(): Removes a validation rule
HTML_QuickForm2_Node::render(): Renders the element using the given renderer
HTML_QuickForm2_Node::renderClientRules(): Adds element's client-side validation rules to a builder object
HTML_QuickForm2_Node::setContainer(): Adds the link to the element containing current
HTML_QuickForm2_Node::setError(): Sets the error message to the element
HTML_QuickForm2_Node::setId(): Sets the element's id
HTML_QuickForm2_Node::setLabel(): Sets the element's label(s)
HTML_QuickForm2_Node::setName(): Sets the element's name
HTML_QuickForm2_Node::setValue(): Sets the element's value
HTML_QuickForm2_Node::storeId(): Stores the explicitly given id to prevent duplicate id generation
HTML_QuickForm2_Node::toggleFrozen(): Changes the element's frozen status
HTML_QuickForm2_Node::updateValue(): Called when the element needs to update its value from form's data sources
HTML_QuickForm2_Node::validate(): Performs the server-side validation

Class Details

[line 60]
Handles a Container that can be repeated multiple times in the form

This element accepts a Container (a Fieldset, a Group, but not another Repeat) serving as a "prototype" and repeats it several times. Repeated items can be dynamically added / removed via Javascript, with the benefit that server-side part automatically knows about these changes and that server-side and client-side validation can be easily leveraged.

Example:

 $group  = new HTML_QuickForm2_Container_Group()

 $repeat = $form->addRepeat('related');
                ->setPrototype($group);
 // repeat indexes will be automatically appended to elements in prototype
 $group->addHidden('related_id');
 $group->addText('related_title');
 // this is identical to $group->addCheckbox('related_active');
 $repeat->addCheckbox('related_active');
 
 // value of this field will be used to find the indexes of repeated items
 $repeat->setIndexField('related_id');

Author: Bertrand Mansion <golgote@mamasam.com>
Author: Alexey Borzov <avb@php.net>
Version: Release: 2.1.0
Link: https://pear.php.net/package/HTML_QuickForm2
License: BSD 3-Clause License

[ Top ]

Class Variables

$childErrors = array()

[line 88]

Errors for (repeated) child elements set during validate() call

Access: protected

Type:

array

[ Top ]

$indexField = null

[line 76]

Field used to search for available indexes

Access: protected

Type:

string

[ Top ]

$itemIndexes = array()

[line 82]

Available indexes

Access: protected

Type:

array

[ Top ]

$passDataSources = false

[line 98]

Whether getDataSources() should return Container's data sources

This is done to prevent useless updateValue() activity in child elements when their values are not going to be needed.

Access: protected

Type:

bool

[ Top ]

Method Detail

appendChild [line 184]

HTML_QuickForm2_Node appendChild(
HTML_QuickForm2_Node
$element)

Appends an element to the prototype container

Elements are kept in the prototype rather than directly in repeat

Return: Added element
Throws: HTML_QuickForm2_InvalidArgumentException
Access: public

Overrides HTML_QuickForm2_Container::appendChild() (Appends an element to the container)

Parameters:

HTML_QuickForm2_Node $element — Element to add

[ Top ]

appendIndexTemplates [line 374]

void appendIndexTemplates(
)

Appends the template to elements' names and ids that will be later replaced by index

Default behaviour is to append '[:idx:]' to element names and '_:idx:' to element ids. If the string ':idx:' is already present in the attribute, then it will not be changed.

Checkboxes and radios may contain ':idx:' in their 'value' attribute, in this case their 'name' attribute is left alone. Names of groups are also not touched.

Access: protected

[ Top ]

backupChildAttributes [line 404]

array backupChildAttributes(
[bool
$backupId = false], [bool
$backupError = false])

Backs up child attributes

Return: backup array
Access: protected

Parameters:

bool	`$backupId`	—	whether to backup id attribute
bool	`$backupError`	—	whether to backup error message

[ Top ]

getChildValues [line 508]

array|null getChildValues(
[bool
$filtered = false])

Returns the array containing child elements' values

Iterates over all available repeat indexes to get values

Access: protected

Overrides HTML_QuickForm2_Container::getChildValues() (Returns the array containing child elements' values)

Parameters:

bool $filtered — Whether child elements should apply filters on values

[ Top ]

getDataSources [line 228]

array getDataSources(
)

Returns the data sources for this element

See: HTML_QuickForm2_Container_Repeat::$passDataSources
Access: protected

Overrides HTML_QuickForm2_Node::getDataSources() (Returns the data sources for this element)

[ Top ]

getIndexes [line 298]

array getIndexes(
)

Returns the indexes for repeated items

Access: public

[ Top ]

getPrototype [line 164]

HTML_QuickForm2_Container getPrototype(
)

Returns the prototype Container

Return: prototype
Throws: HTML_QuickForm2_NotFoundException if prototype was not set
Access: protected

[ Top ]

getType [line 105]

string getType(
)

Returns the element's type

Access: public

Overrides HTML_QuickForm2_Node::getType() (Returns the element's type)

[ Top ]

__construct (Constructor) [line 132]

HTML_QuickForm2_Container_Repeat __construct(
[string
$name = null], [string|array
$attributes = null], [array
$data = array()])

Class constructor

Repeat element can understand the following keys in $data parameter:

'prototype': a Container to be repeated. Passed to setPrototype().

Access: public

Overrides HTML_QuickForm2_Node::__construct() (Class constructor)

Parameters:

string	`$name`	—	Element name
string\|array	`$attributes`	—	Attributes (either a string or an array)
array	`$data`	—	Additional element data

[ Top ]

insertBefore [line 215]

HTML_QuickForm2_Node insertBefore(
HTML_QuickForm2_Node
$element, [HTML_QuickForm2_Node
$reference = null])

Inserts an element to the prototype container

Elements are kept in the prototype rather than directly in repeat

Return: Inserted element
Access: public

Overrides HTML_QuickForm2_Container::insertBefore() (Inserts an element in the container)

Parameters:

HTML_QuickForm2_Node	`$element`	—	Element to insert
HTML_QuickForm2_Node	`$reference`	—	Reference to insert before

[ Top ]

removeChild [line 199]

HTML_QuickForm2_Node removeChild(
HTML_QuickForm2_Node
$element)

Removes the element from the prototype container

Elements are kept in the prototype rather than directly in repeat

Return: Removed object
Throws: HTML_QuickForm2_NotFoundException
Access: public

Overrides HTML_QuickForm2_Container::removeChild() (Removes the element from this container)

Parameters:

HTML_QuickForm2_Node $element — Element to remove

[ Top ]

render [line 621]

HTML_QuickForm2_Renderer render(
HTML_QuickForm2_Renderer
$renderer)

Renders the container using the given renderer

Container will be output N + 1 times, where N are visible items and 1 is the hidden prototype used by Javascript code to create new items.

Access: public

Overrides HTML_QuickForm2_Container::render() (Renders the container using the given renderer)

Parameters:

HTML_QuickForm2_Renderer $renderer — renderer to use

[ Top ]

renderClientRules [line 592]

void renderClientRules(
HTML_QuickForm2_JavascriptBuilder
$builder)

Adds element's client-side validation rules to a builder object

This will also call forceValidator() if the repeat does not contain any (visible) items but some of the child elements define client-side rules

Access: protected

Overrides HTML_QuickForm2_Node::renderClientRules() (Adds element's client-side validation rules to a builder object)

Parameters:

HTML_QuickForm2_JavascriptBuilder $builder —

[ Top ]

replaceIndexTemplates [line 473]

void replaceIndexTemplates(
int
$index, array
$backup)

Replaces a template in elements' attributes by a numeric index

See: HTML_QuickForm2_Container_Repeat::backupChildAttributes()
Access: protected

Parameters:

int	`$index`	—	numeric index
array	`$backup`	—	backup array, contains attributes with templates

[ Top ]

restoreChildAttributes [line 438]

void restoreChildAttributes(
array
$backup)

Restores child attributes from backup array

See: HTML_QuickForm2_Container_Repeat::backupChildAttributes()
Access: protected

Parameters:

array $backup — backup array

[ Top ]

setIndexes [line 316]

$this setIndexes(
array
$indexes)

Sets the indexes for repeated items

As is the case with elements' values, the indexes will be updated from data sources, so use this after all possible updates were done.

Access: public

Parameters:

array $indexes —

[ Top ]

setIndexField [line 249]

$this setIndexField(
string
$field)

Sets a field to check for available indexes

Form data sources will be searched for this field's value, indexes present in the array will be used for repeated elements. Use the field that will be always present in submit data: checkboxes, multiple selects and fields that may be disabled are bad choices

Access: public

Parameters:

string $field — field name

[ Top ]

setPrototype [line 148]

$this setPrototype(
HTML_QuickForm2_Container
$prototype)

Sets the Container that will be used as a prototype for repeating

Access: public

Parameters:

HTML_QuickForm2_Container $prototype — prototype container

[ Top ]

setValue [line 117]

void setValue(
mixed
$value)

Sets the element's value (not implemented)

Throws: HTML_QuickForm2_Exception
Access: public

Overrides HTML_QuickForm2_Node::setValue() (Sets the element's value)

Parameters:

mixed $value — element's value

[ Top ]

updateValue [line 337]

void updateValue(
)

Called when the element needs to update its value from form's data sources

Behaves similar to Element::updateValue(), the field's value is used to deduce indexes taken by repeat items.

See: HTML_QuickForm2_Container_Repeat::setIndexField()
Throws: HTML_QuickForm2_Exception
Access: protected

Overrides HTML_QuickForm2_Container::updateValue() (Called when the element needs to update its value from form's data sources)

[ Top ]

validate [line 530]

boolean validate(
)

Performs the server-side validation

Iterates over all available repeat indexes and calls validate() on prototype container.

Return: Whether the repeat and all repeated items are valid
Access: protected

Overrides HTML_QuickForm2_Container::validate() (Performs the server-side validation)

[ Top ]