Добро пожаловать на форум PHP программистов!
За последние 24 часа нас посетили 16956 программистов и 1772 робота. Сейчас ищут 1405 программистов ...

Elements

Вернуться к: HTML_QuickForm2

Elements

Elements – Base Element API and list of built-in Elements

Element classes in HTML_QuickForm2, including HTML_QuickForm2 itself, are descended from either HTML_QuickForm2_Container or HTML_QuickForm2_Element, class tree for those two abstract classes given below. Common API for elements is mostly defined in HTML_QuickForm2_Node.

As can be seen from the above tree, all elements are descended from HTML_Common2, so you have access to attribute-handling methods defined in that class. Please refer to HTML_Common2 documentation for more info.

HTML_QuickForm2_Node API overview

Only public methods that are of interest to package users are described in this section. Other methods are mostly useful for those wishing to extends the package and will be described in a separate documentation section targeted at them.

Constructors of all the elements have the same list of parameters, as defined in HTML_QuickForm2_Node:

string $name

Element name

string|array $attributes

HTML attributes

array $data

Additional element-specific data. A 'label' key in this array is understood by every element and is used for element's label. Other possible keys are described in the tables below.

As a result, HTML_QuickForm2_Factory::createElement() and HTML_QuickForm2_Container::addElement() that pass their arguments to the element's constructor also have constant list of parameters, the first being element type and subsequent ones corresponding to constructor parameters.

Getters and setters for miscellaneous element properties: setName() / getName(), setId() / getId(), setLabel() / getLabel(), getContainer(), getData(), getType().

Setter methods in HTML_QuickForm2 tend to return $this, so that it is possible to chain their invocations:

<?php
$text
->setName('aText')
     ->
setLabel('Text input field:');
?>

Methods for getting and changing elements' values: setValue(), getValue(), getRawValue(). Their detailed description is in the next section.

Filtering the elements' values is done by addFilter() and addRecursiveFilter() methods. The former is applied directly to element's value on getValue() call and the latter is propagated to contained elements if the element is a Container or applied recursively to the value if element's value is an array.

Validation-related methods: setError() / getError(), createRule(), addRule() / removeRule(), isRequired(). Please consult the section on validation.

The elements implement magic __toString() method so they can be used in string contexts:

<?php
$element 
= new HTML_QuickForm2_Element_InputText(
    
'textBox', array('size' => 20'id' => 'textBoxId')
);
echo 
$element;
?>

with output being

 
<input type="text" id="textBoxId" size="20" name="textBox" />

More complex output needs are covered by render() method.

A helpful feature of HTML_QuickForm2 is the ability to "freeze" form elements, displaying their values without HTML input tags. This may be used for an additional confirmation step after form submit or for sending a filled form via email, among other things. Two methods deal with this: toggleFrozen() and persistentFreeze(), the former toggling the "frozen" status and the latter "persistent freeze" behaiour. If persistent freeze is on, element's value will be kept (and possibly submitted) in a hidden field.

Freezing the element

<?php
$box 
= new HTML_QuickForm2_Element_InputCheckbox(
    
'aBox', array('value' => 'boxValue''checked' => 'checked')
);
echo 
$box "\n\n";

$box->toggleFrozen(true);
echo 
$box "\n\n";

$box->persistentFreeze(false);
echo 
$box;
?>

the above code results in

 
<input type="checkbox" value="boxValue" checked="checked" name="aBox" id="aBox-0" />

<tt>[x]</tt><input type="hidden" name="aBox" value="boxValue" id="aBox-0" />

<tt>[x]</tt>

HTML_QuickForm2_Container API overview

In addition to methods defined in HTML_QuickForm2_Node, Container defines DOM-like API for handling of child elements: appendChild(), insertBefore(), removeChild(), getElementById(), getElementsByName(). Those who have worked with Javascript or PHP's DOM extension should find these familiar.

DOM-like API for Container

<?php
$fieldset 
= new HTML_QuickForm2_Container_Fieldset();

$radioOne $fieldset->appendChild(
    new 
HTML_QuickForm2_Element_InputRadio('aRadio', array('id' => 'radioOne'))
);
$radioThree $fieldset->appendChild(
    new 
HTML_QuickForm2_Element_InputRadio('aRadio', array('id' => 'radioThree'))
);
$radioTwo $fieldset->insertBefore(
    new 
HTML_QuickForm2_Element_InputRadio('aRadio', array('id' => 'radioTwo')),
    
$radioThree
);

echo 
$fieldset->getElementById('radioOne') . "\n\n";
$fieldset->removeChild($radioOne);
foreach (
$fieldset->getElementsByName('aRadio') as $radio) {
    echo 
$radio "\n";
}
?>

will output

 
<input type="radio" value="on" id="radioOne" name="aRadio" />

<input type="radio" value="on" id="radioTwo" name="aRadio" />
<input type="radio" value="on" id="radioThree" name="aRadio" />

A few convenience methods are also available: getElements() returns an array with all the Container's elements and addElement() creates an element of a given type and adds it to the Container. Thanks to method overloading you can also perform addEltype() calls where 'eltype' is an element type known to HTML_QuickForm2_Factory (see below for the list of such types and examples).

Container also implements Countable and IteratorAggregate SPL interfaces, allowing to easily count the immediate children and iterate over them. It also has getRecursiveIterator() method which returns an instance of HTML_QuickForm2_ContainerIterator for recursive iteration over all child elements.

SPL interfaces support

<?php
$outer 
= new HTML_QuickForm2_Container_Fieldset();
$inner $outer->addElement('fieldset')->setId('inner');
$inner->addElement('text''textName')->setId('textId');

echo 
count($outer) . "\n";
foreach (
$outer as $child) {
    echo 
$child->getId() . "\n";
}
echo 
"\n";
foreach (
$outer->getRecursiveIterator() as $child) {
    echo 
$child->getId() . "\n";
}
?>

The above code will output

 
1
inner

inner
textId

List of elements

The following is a list of non-abstract descendants of HTML_QuickForm2_Node. These elements are pre-registered with HTML_QuickForm2_Factory and thus can be instantiated with HTML_QuickForm2_Factory::createElement() and added to a Container with either HTML_QuickForm2_Container::addElement() or its overloaded addEltype() method using "Type name" from tables below.

<?php
// will create an instance of HTML_QuickForm2_Element_Textarea
$area HTML_QuickForm2_Factory::createElement('textarea''areaName');
// will add a new instance of HTML_QuickForm2_Element_Select to $container
$select $container->addElement('select''selectName');
// will add a new instance of HTML_QuickForm2_Element_InputText to $container
$text $container->addText('textName');
?>

New element types can be registered by HTML_QuickForm2_Factory::registerElement(), HTML_QuickForm2_Factory::isElementRegistered() checks whether an element is known to Factory.

<?php
HTML_QuickForm2_Factory
::registerElement(
    
'dualselect''HTML_QuickForm2_Element_DualSelect'
);

// ...

if (HTML_QuickForm2_Factory::isElementRegistered('dualselect')) {
    
$form->addElement('dualselect''dualselectDemo'$attributes$config);
}
?>

Standard HTML form elements
Type name Class Description, extra $data keys
'button' HTML_QuickForm2_Element_Button <button></button> elements. $data may contain 'content' key with HTML to add between <button></button> tags.
'checkbox' HTML_QuickForm2_Element_InputCheckbox <input type="checkbox" /> elements. $data may contain 'content' key with a label that should be "glued" to checkbox.
'fieldset' HTML_QuickForm2_Container_Fieldset <fieldset></fieldset> elements, labels for them will be rendered as <legend></legend>.
'file' HTML_QuickForm2_Element_InputFile <input type="file" /> elements. This element validates itself by checking a relevant 'error' field in $_FILES array. $data may contain 'messageProvider' and 'language' keys for setting up localized error messages.
'hidden' HTML_QuickForm2_Element_InputHidden <input type="hidden" /> elements
'image' HTML_QuickForm2_Element_InputImage <input type="image" /> elements
'inputbutton' HTML_QuickForm2_Element_InputButton <input type="button" /> elements
'password' HTML_QuickForm2_Element_InputPassword <input type="password" /> elements
'radio' HTML_QuickForm2_Element_InputRadio <input type="radio" /> elements. $data may contain 'content' key with a label that should be "glued" to radiobutton.
'reset' HTML_QuickForm2_Element_InputReset <input type="reset" /> elements
'select' HTML_QuickForm2_Element_Select

<select></select> elements. $data may contain the following keys

'options'

Data to populate element's options with. Passed to HTML_QuickForm2_Element_Select::loadOptions().

'intrinsic_validation'

By default only submit values corresponding to options present in the element are returned. Setting this to FALSE will return all submit values (useful if options are added on client side).

'submit' HTML_QuickForm2_Element_InputSubmit <input type="submit" /> elements
'text' HTML_QuickForm2_Element_InputText <input type="text" /> elements
'textarea' HTML_QuickForm2_Element_Textarea <textarea></textarea> elements
Custom elements
Type name Class Description, extra $data keys
'date' HTML_QuickForm2_Element_Date

Group of selects used to input dates (and times). $data may contain

'messageProvider'

Message provider for localized names of months and weekdays.

'language'

Date language, using 'locale' will display month / weekday names according to the current locale.

'format'

Format of the date, based on PHP's date(). Format characters recognized: 'D', 'l', 'd', 'M', 'F', 'm', 'Y', 'y', 'h', 'H', 'i', 's', 'a', 'A'.

'minYear'

Minimum year in year select

'maxYear'

Maximum year in year select

'addEmptyOption'

Whether an empty option should be added to the top of each select box

'emptyOptionValue'

The value passed by the empty option

'emptyOptionText'

The text displayed for the empty option

'optionIncrement'

Step to increase the option values by (works for 'i' and 's')

'minHour'

Minimum hour in hour select (only for 24 hour format)

'maxHour'

Maximum hour in hour select (only for 24 hour format)

'minMonth'

Minimum month in month select

'maxMonth'

Maximum month in month select

'group' HTML_QuickForm2_Container_Group Group of form elements. Several elements may be grouped into a single entity and this entity used as a single element. Date and Hierselect are based on Group.
'hierselect' HTML_QuickForm2_Element_Hierselect

Hierarchical select element. Two or more select elements, selecting the value in the first changes options in the second and so on. $data may contain

'options'

Data to populate child elements' options with. Passed to HTML_QuickForm2_Element_Hierselect::loadOptions().

'size'

number of selects in hierselect. If not given will be set from size of options array or size of array passed to HTML_QuickForm2_Element_Hierselect::setValue().

Everything else is passed on to created selects.

'script' HTML_QuickForm2_Element_Script Class for adding inline javascript to the form, based on Static.
'static' HTML_QuickForm2_Element_Static

A pseudo-element used to add text or markup to the form, when that text should be output similar to form element. $data may contain

'content'

Content of the static element, text or markup.

'tagName'

Name of the tag to wrap around content, e.g. 'div'. The tag will use Static element's attributes.

'forceClosingTag'

Whether to output closing tag in case of empty content, <foo></foo> vs. <foo />.



Вернуться к: HTML_QuickForm2

© 2024 «PHP.RU — Сообщество PHP-Программистов»
Главная | Форум | Реклама на сайте | Контакты VIP Сувениры
Разработка компании ODware