|
FreePBX API: HTML_QuickForm
Part of the ApiDocs
HTML_Quickform is a (PEAR library used to create and process forms.
Web Links
- HTML_Quickform Documentation
- PEAR's QuickForm Quick Start tutorial
- Keith Edmunds' QuickForm tutorial
Element Reference
Note: This was copied from Keith Edmunds' tutorial. Some of his examples have been omitted/shortened.
advcheckbox
Normally a checkbox only passes a value back to the form when it is checked. Unchecked boxes not only pass no value back, but also the checkbox variable does not exist in the values passed to the process routine. The advcheckbox overcomes these problems.
addElement('advcheckbox',
string element-name, // name of advcheckbox
string element-label, // label output before advcheckbox
string text, // label output after advcheckbox
mixed attributes, // string or array of attributes
mixed values); // see below
If values is omitted then the value returned is an empty string if not checked, and '1' if checked. If a string value is passed then the return value is empty string/supplied string, and if an array of two strings is passed they are taken as the unchecked/checked values to return.
advmultiselect
This is a special select element for selecting multiple options. It can either be presented as two select boxes (available and selected) with buttons to move items between them, or a list with a checkbox next to each item.
addElement('advmultiselect',
string element-name, // name of advcheckbox
string element-label, // label output before advcheckbox
array options, // data to be used to populate options
mixed attributes, // string or array of attributes
mixed sort); // Either SORT_ASC for auto ascending arrange, SORT_DESC for auto descending arrange, or NULL for no sort (append at end: default)
For full documentation see PEAR HTML_QuickForm_advmultiselect documentation or The definitive guide
button
addElement('button',
string element-name, // name of button
string value, // text of button
mixed attributes); // string or array of attributes
checkbox
addElement('checkbox',
string element-name, // name of checkbox
string element-label, // label output before checkbox
string text, // label output after checkbox
mixed attributes); // string or array of attributes
date
This pseudo-element produces multiple select boxes for the user to input a date and/or time.
addElement('date',
string element-name, // name of date
string element-label, // label output before date
array options, // see below
mixed attributes); // string or array of attributes
options is an array which sets the language, the date/time format, and the minimum and maximum year offered in the select boxes. The format string determines not only the date/time format, but also the number of select boxes shown. The value of the date returned is an associative array, each element key being the relevant format character and the value being the value selected by the user.
file
Note: The 'file' documentation was submitted by Leonie Price
addElement('file',
string element-name, // name of file element
string element_label, // label for file element
mixed attributes); // string or array of attributes
This is a pseudo-element that displays a text box and button, and provides all the supporting functions needed to manage the uploading of files.
Warning: The official documentation records this element as being depreciated, and may not be supported in future versions of QuickForm.
header
addElement('header',
string element-name, // name of header
string text); // text of header
hidden
addElement('hidden',
string element-name, // name of hidden element
string value, // value of hidden element
mixed attributes); // string or array of attributes
hierselect
This pseudo-element dynamically creates two HTML Select elements. The values available in the second Select element are determined by the value selected in the first. For example, the first box could list countries and the second cities; only the cities which exist in the selected country would be available.
addElement('hierselect',
string element-name, // name of hierselect element
string label, // text label
mixed attributes); // string or array of attributes
The methods setMainOptions and setSecOptions are used to populate the two select boxes. The argument to setMainOptions is a single dimension array; the argument to setSecOptions is a two-dimension array, the first dimension being the key used to associate the secondary option to the appropriate main option. The value returned is a two-element array, the first element being the value of the main option and the second element being the value of the secondary options. An example should make the use of hierselect easier to understand:
<?php
$main[0] = "England";
$main[1] = "Scotland";
$main[2] = "USA";
$secondary[0][0] = "London";
$secondary[0][1] = "Manchester";
$secondary[0][2] = "Liverpool";
$secondary[1][3] = "Edinburgh";
$secondary[1][4] = "Glasgow";
$secondary[2][5] = "Fort Worth";
$secondary[2][6] = "Boston";
$secondary[2][7] = "Los Angles";
$sel =& $form->addElement('hierselect', 'location', 'Location:');
$sel->setMainOptions($main);
$sel->setSecOptions($secondary);
$form->addElement('submit', 'btnSubmit', 'Submit');
Warning: Note that if a default value for the main box is set this does not automatically set the contents for the secondary box
Set default as follows:
// First part of form as previous example
$form->setDefaults(array('location'=>array(1,4)));
$sel =& $form->addElement('hierselect', 'location', 'Location:');
html
This pseudo-element adds raw HTML to a form.
addElement('html',
string html-text); // the HTML to add
Warning: this element is depreciated
image
Adds an image to a form.
addElement('image',
string element-name, // name for image
string src, // source file of image
mixed attributes); // string or array of attributes
link
Creates a link.
addElement('link',
string element-name, // name for link
string label, // label for link field
string href, // URI of link
string text, // text to display
mixed attributes); // string or array of attributes
password
addElement('password',
string element-name, // name for password
string label, // label for password field
mixed attributes); // string or array of attributes
radio
addElement('radio',
string element-name, // name for radio button
string label, // text to display before button
string text, // text to display after button
int value, // the value returned
mixed attributes); // string or array of attributes
Note: Adding multiple radio buttons with the same element-name will cause them to behave as a group (ie, only one can be selected).
To select a default radio button from a group, use:
$form->setDefaults(array(element-name => value));
reset
addElement('reset',
string element-name, // name of reset
string value, // text of button
mixed attributes); // string or array of attributes
select
addElement('select',
string element-name, // name of select
string label, // label for select
mixed data, // data for select; see earlier text
mixed attributes); // string or array of attributes
static
This element displays static text on the form.
addElement('static',
string label, // label to display
string text); // text to display
submit
addElement('submit',
string element-name, // name of submit
string value, // text of button
mixed attributes); // string or array of attributes
text
addElement('text',
string element-name, // name of text box
string label, // label
mixed attributes); // string or array of attributes
textarea
addElement('textarea',
string element-name, // name of textarea
string label, // label
mixed attributes); // string or array of attributes
