Package: Controls

Class: Zebra_Form_Select

source file: /includes/Select.php

Class Overview


Class for select box controls.



  • (c) 2006 - 2016 Stefan Gabos

Inherited methods

Class: Zebra_Form_Control

Call this method to instruct the script to force all letters typed by the user, to either uppercase or lowercase, in real-time.
Disables the SPAM filter for the control.
Disables XSS filtering of the control's submitted value.
Returns the values of requested attributes.
Locks the control's value. A locked control will preserve its default value after the form is submitted even if the user altered it.
Resets the control's submitted value (empties text fields, unchecks radio buttons/checkboxes, etc).
Sets one or more of the control's attributes.
Sets a single or an array of validation rules for the control.
Converts the array with control's attributes to valid HTML markup interpreted by the toHTML() method

Class: XSS_Clean

Sanitizes submitted data so that Cross Site Scripting Hacks can be prevented.

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.

  1. // create a new form
  2. $form new Zebra_Form('my_form');
  4. // single-option select box
  5. $obj $form->add('select''my_select');
  7. // add selectable values with default indexes
  8. // values will be "0", "1" and "2", respectively
  9. // a default first value, "- select -" (language dependent) will also be added
  10. $obj->add_options(array(
  11.     'Value 1',
  12.     'Value 2',
  13.     'Value 3'
  14. ));
  16. // single-option select box
  17. $obj $form->add('select''my_select2');
  19. // add selectable values with specific indexes
  20. // values will be "v1", "v2" and "v3", respectively
  21. // a default first value, "- select -" (language dependent) will also be added
  22. $obj->add_options(array(
  23.     'v1' => 'Value 1',
  24.     'v2' => 'Value 2',
  25.     'v3' => 'Value 3'
  26. ));
  28. // single-option select box with the second value selected
  29. $obj $form->add('select''my_select3''v2');
  31. // add selectable values with specific indexes
  32. // values will be "v1", "v2" and "v3", respectively
  33. // also, overwrite the language-specific default first value (notice the boolean TRUE at the end)
  34. $obj->add_options(array(
  35.     ''   => '- select a value -',
  36.     'v1' => 'Value 1',
  37.     'v2' => 'Value 2',
  38.     'v3' => 'Value 3'
  39. )true);
  41. // multi-option select box with the first two options selected
  42. $obj $form->add('select''my_select4[]'array('v1''v2')array('multiple' => 'multiple'));
  44. // add selectable values with specific indexes
  45. // values will be "v1", "v2" and "v3", respectively
  46. $obj->add_options(array(
  47.     'v1' => 'Value 1',
  48.     'v2' => 'Value 2',
  49.     'v3' => 'Value 3'
  50. ));
  52. // don't forget to always call this method before rendering the form
  53. if ($form->validate()) {
  54.     // put code here
  55. }
  57. // output the form using an automatically generated template
  58. $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!

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.

  1. // in a template file, in order to print the generated HTML
  2. // for a control named "my_select", one would use:
  3. 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.

  1. // setting the "multiple" attribute
  2. $obj $form->add(
  3.     'select',
  4.     'my_select',
  5.     '',
  6.     array(
  7.         'multiple' => 'multiple'
  8.     )
  9. );

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)

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!

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:

  1. // add as groups:
  2. $obj->add_options(array(
  3.     'group' => array('option 1''option 2')
  4. ));
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


method toHTML()

string toHTML ( )

Generates the control's HTML code.

This method is automatically called by the render() method!

return: The control's HTML code