Custom Group-based elements
Date element
HTML_QuickForm2_Element_Date is a
group of <select></select> elements used to input dates (and
times). Child selects are created according to 'format' parameter.
$data parameter for element's
constructor may contain the following custom keys:
'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. May be also set on a
per-element basis:
array('Y' => false, 'd' => true);
'emptyOptionValue'- The value passed by the empty option
'emptyOptionText'-
The text displayed for the empty option. May be also set on a per-element basis:
array('Y' => 'Choose year', 'd' => 'Choose day');
'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
Child selects of Date element are named according to
'format' parameter, so Date's value can be set using the standard
approach for groups:
<?php
$date = $form->addElement(
'date', 'testDate', null,
array('format' => 'd-F-Y', 'minYear' => date('Y'), 'maxYear' => 2001)
);
// sets the date to January 1st, 2012
$date->setValue(array('d' => 1, 'F' => 1, 'Y' => 2012));
?>
Additionally Date's setValue() method may accept a string containing a date or a number representing Unix timestamp:
<?php
// also sets the date to January 1st, 2012
$date->setValue('2012-01-01');
// once again sets the date to January 1st, 2012
$date->setValue(1325408400);
?>
String representation of a date is processed by strtotime() function, so consider its limitations.
Hierselect element
Hierselect requires
quickform.jsandquickform-hierselect.jsfiles being included in the page to work.
HTML_QuickForm2_Element_Hierselect is
a group of two or more chained <select></select> elements.
Selecting a value in the first select changes options in the second and so on.
$data parameter for element's
constructor may contain the following custom keys:
'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 except 'label' is passed on to created selects.
Options for select elements are added using HTML_QuickForm2_Element_Hierselect::loadOptions() method:
<?php
$categories = array(
1 => 'HTML',
2 => 'HTTP'
);
// first keys are needed to find related options
$packages = array(
1 => array(
1 => 'HTML_AJAX',
2 => 'HTML_Common2',
3 => 'HTML_QuickForm2'
),
2 => array(
1 => 'HTTP_Download',
2 => 'HTTP_Request2'
)
);
$hierselect->loadOptions(array($categories, $packages));
?>
Unlike old hierselect element from HTML_QuickForm you don't need to provide all possible options. You may instead give server-side and client-side callbacks that will receive values of previous selects and return additional options as needed:
<?php
$hierselect->loadOptions(
array($categories, array()),
array($loader, 'getPackages'), 'loadPackagesSync'
);
?>
hierselect-ajax.phpexample file installed with the package shows how to use AJAX requests to load additional options.