Class: Zebra_Form_Select
source file: /includes/Select.php
Class Overview
XSS_Clean
|
--Zebra_Form_Control
|
--Zebra_Form_Select
Class for select box controls.
Author(s):
Copyright:
- (c) 2006 - 2013 Stefan Gabos
Class methods
constructor __construct()
void
__construct (
string
$id
,
[
mixed
$default
= '']
,
[
array
$attributes
= '']
,
[
string
$default_other
= '']
)
Adds an <select> control to the form.
Do not instantiate this class directly! Use the add() method instead! By default, unless the multiple attribute is set, the control will have a default first option added automatically inviting users to select one of the available options. Default value for English is "- select -" taken from the language file - see the language() method. If you don't want it or want to set it at runtime, set the overwrite argument to TRUE when calling the add_options() method. // create a new form // single-option select box $obj = $form->add('select', 'my_select'); // add selectable values with default indexes // values will be "0", "1" and "2", respectively // a default first value, "- select -" (language dependent) will also be added 'Value 1', 'Value 2', 'Value 3' )); // single-option select box $obj = $form->add('select', 'my_select2'); // add selectable values with specific indexes // values will be "v1", "v2" and "v3", respectively // a default first value, "- select -" (language dependent) will also be added 'v1' => 'Value 1', 'v2' => 'Value 2', 'v3' => 'Value 3' )); // single-option select box with the second value selected $obj = $form->add('select', 'my_select3', 'v2'); // add selectable values with specific indexes // values will be "v1", "v2" and "v3", respectively // also, overwrite the language-specific default first value (notice the boolean TRUE at the end) '' => '- select a value -', 'v1' => 'Value 1', 'v2' => 'Value 2', 'v3' => 'Value 3' ), true); // multi-option select box with the first two options selected $obj = $form->add('select', 'my_select4[]', array('v1', 'v2'), array('multiple' => 'multiple')); // add selectable values with specific indexes // values will be "v1", "v2" and "v3", respectively 'v1' => 'Value 1', 'v2' => 'Value 2', 'v3' => 'Value 3' )); // don't forget to always call this method before rendering the form if ($form->validate()) { // put code here } // output the form using an automatically generated template $form->render();
By default, for checkboxes, radio buttons and select boxes, the library will prevent the submission of other
values than those declared when creating the form, by triggering the error: "SPAM attempt detected!". Therefore,
if you plan on adding/removing values dynamically, from JavaScript, you will have to call the
disable_spam_filter() method to prevent that from happening! Parameters:
| string |
$id |
Unique name to identify the control in the form. The control's name attribute will be as specified by the $id argument.
The id attribute will be as specified by the $id argument but with square brackets trimmed off (if any). This is the name to be used when referring to the control's value in the POST/GET superglobals, after the form is submitted. This is also the name of the variable (again, with square brackets trimmed off if it's the case) to be used in the template file, containing the generated HTML for the control. // in a template file, in order to print the generated HTML // for a control named "my_select", one would use: echo $my_select;
|
| mixed |
$default |
(Optional) Default selected option. This argument can also be an array in case the multiple attribute is set and multiple options need to be preselected by default. |
| array |
$attributes |
(Optional) An array of attributes valid for select controls (multiple, readonly, style, etc) Must be specified as an associative array, in the form of attribute => value. // setting the "multiple" attribute $obj = $form->add( 'select', 'my_select', '', array( 'multiple' => 'multiple' ) );
Special attribute: When setting the special attribute other to true, a textbox control will be automatically created having the name [id]_other where [id] is the select control's id attribute. The text box will be hidden until the user selects the automatically added Other... option (language dependent) from the selectable options. The option's value will be other. If the template is not automatically generated you will have to manually add the automatically generated control to the template. See set_attributes() on how to set attributes, other than through the constructor. The following attributes are automatically set when the control is created and should not be altered manually:
id, name |
| string |
$default_other |
The default value in the "other" field (if the "other" attribute is set to true, see above) |
Top
method add_options()
void
add_options (
array
$options
,
[
boolean
$overwrite
= false]
)
Adds options to the select box control
If the "multiple" attribute is not set, the first option will be always considered as the "nothing is selected"
state of the control!
Parameters:
| array |
$options |
An associative array of options where the key is the value of the option and the value is the actual text to be displayed for the option. Option groups can be set by giving an array of associative arrays as argument: // add as groups: 'group' => array('option 1', 'option 2') ));
|
| boolean |
$overwrite |
(Optional) By default, succesive calls of this method will appended the options given as arguments to the already existing options. Setting this argument to TRUE will instead overwrite the previously existing options. Default is FALSE |
Top
method toHTML()
string
toHTML (
)
Generates the control's HTML code.
This method is automatically called by the render() method!
Tags:
| return: |
The control's HTML code |
Top
|