Element values and Data sources

Element values and Data sources – Setting and getting values for the whole form and for individual elements

Individual elements' values

Each element in HTML_QuickForm2 implements getRawValue() and getValue() methods that return its unfiltered and filtered submit value, respectively, and setValue() that sets the element's display value. These are not always the same, consider

<?php
$text 
= new HTML_QuickForm2_Element_InputText(
    
'testText', array('disabled' => 'disabled')
);
$text->setValue('a value');
echo 
$text "\n";
var_dump($text->getValue());
?>

which produces


<input type="text" disabled="disabled" name="testText" id="testText-0" value="a value" />
NULL

as disabled elements cannot have a submit value.

If an element can not have a submit value (e.g. reset button, static element) or does not currently have one (e.g. disabled element, unchecked checkbox) then getValue() will return NULL. The value also passes "intrinsic validation" which ensures that it could possibly come from that element:

<?php
$select 
HTML_QuickForm2_Factory::createElement('select''testSelect',
                                                 array(
'multiple' => 'multiple'))
              ->
loadOptions(array('a' => 'letter A''b' => 'letter B''c' => 'letter C'));
$select->setValue(array('a''z'));
// select will only return values for options that were present in it
var_dump($select->getValue());
?>

will output


array(1) {
  [0]=>
  string(1) "a"
}

On the other hand, some of the elements cannot have a display value (<input type="image" />, file uploads), setValue() will be a no-op for such elements and they will only get their values (click coordinates and file upload data, respectively) from submit data sources.

getValue() / getRawValue() also work for Containers and return an array with values of contained elements. setValue() is only implemented for groups, data sources should be used to set the values for the whole form.

Data sources overview

Instance of HTML_QuickForm2 contains an array of Data sources - objects storing elements' incoming values. These values may either originate from HTTP request data (submit values) or be provided by the programmer (default values). Data sources implement HTML_QuickForm2_DataSource interface defining a single getValue() method, which receives element name and returns either element value or NULL if such value is not present.

There is also a HTML_QuickForm2_DataSource_Submit interface that defines an additional getUpload() method that receives file upload name and returns either file upload data from $_FILES array or NULL if it doesn't contain this data.

A data source containing submit values will be added to the list automatically if constructor of HTML_QuickForm2 considers the form submitted. You can add another data source to the list using HTML_QuickForm2::addDataSource() and completely replace the list using HTML_QuickForm2::setDataSources().

An element will try to update its value from data sources in the following cases:

  • It is added to the form;
  • Its name is changed;
  • Form data sources list is changed.

To perform that update it gets the data sources array from the form and iterates over it calling getValue() until a non-NULL value is returned. This value is then used as element's value.

Some of the elements (submit buttons, obviously file uploads) will only consider getting their values from instances of HTML_QuickForm2_DataSource_Submit. Some (e.g. checkboxes) will stop iterating over the array as soon as an instance of HTML_QuickForm2_DataSource_Submit is found, even if its getValue() method returns NULL. Static elements will only consider a datasource if it is not an instance of HTML_QuickForm2_DataSource_Submit.

Implementations of HTML_QuickForm2_DataSource

The package contains several classes implementing the HTML_QuickForm2_DataSource interface, but the only one that should be used directly is HTML_QuickForm2_DataSource_Array, other classes are used internally by the package.

An instance of HTML_QuickForm2_DataSource_Array wraps around an array with a structure similar to that of superglobal $_GET / $_POST arrays. This wrapper allows searching for values of elements with complex names:

<?php
$ds 
= new HTML_QuickForm2_DataSource_Array(array(
    
'foo' => 'foo value',
    
'bar' => array('bar 1''bar 2'),
    
'baz' => array('first' => array('second' => 'found a value'))
));
echo 
$ds->getValue('foo') . "\n";
echo 
$ds->getValue('bar[1]') . "\n";
echo 
$ds->getValue('baz[first][second]');
?>

outputs


foo value
bar 2
found a value

Instead of loading data from a database unconditionally and passing it to this data source in an array, it may make sense to create your own data source implementation, which will only perform a query when asked for a value. This way you will probably save a query on form submit, as all values will be found in a submit data source.

Maintaining correct order

A most popular value-related error happens when a programmer uses an element's setValue() method before adding that element to the form:

<?php
$form
->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
    
'testDefault' => 'duh!'
)));
$element HTML_QuickForm2_Factory::createElement('text''testDefault')
               ->
setValue('my carefully prepared value');
$form->appendChild($element);
echo 
$element->getValue();
?>

As described above, the element will immediately try to update its value from form's data sources and overwrite whatever was set on the previous step, so the above results in


duh!

A less obvious problem is adding data sources after elements:

<?php
// an element updates its value from existing (e.g. submit) data sources
$form->addElement('text''testDefault');
// it updates its value again
$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
    
'testDefault' => 'my carefully prepared value'
)));
// ...and yet again
$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
    
'unrelated' => 'a completely unrelated value'
)));
?>

That code behaves as expected, but performs lots of unneeded work.

To sum it up, a correct order is:

  1. Add all data sources to the form;
  2. Add all elements to the form;
  3. Call setValue() on some elements, if still needed.
Element values and validation (Previous) Checking that you get the values you need (Next)
Last updated: Fri, 19 Dec 2014 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by: cweiske
There is currently no way to set a new value to a group of radio elements - you have to do it manually.

First, get the currently active radio element and call
> removeAttribute('checked')
on it. Then fetch the new radio element and call
> setAttribute('checked')