Custom Group-based elements

Custom Group-based elements – Date and Hierselect

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.js and quickform-hierselect.js files 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(
     
=> 'HTML',
     
=> 'HTTP'
);

// first keys are needed to find related options
$packages = array(
    
=> array(
        
=> 'HTML_AJAX',
        
=> 'HTML_Common2',
        
=> 'HTML_QuickForm2'
    
),
    
=> array(
        
=> 'HTTP_Download',
        
=> '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.php example file installed with the package shows how to use AJAX requests to load additional options.