Package: Controls

Class: Zebra_Form_Checkbox

source file: /includes/Checkbox.php

Class Overview


Class for checkbox 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 $value , [ array $attributes = ''] )

Constructor of the class

Adds an <input type="checkbox"> control to the form.

Do not instantiate this class directly! Use the add() method instead!

  1. // create a new form
  2. $form new Zebra_Form('my_form');
  4. // single checkbox
  5. $obj $form->add('checkbox''my_checkbox''my_checkbox_value');
  7. // multiple checkboxes
  8. // notice that is "checkboxes" instead of "checkbox"
  9. // checkboxes values will be "0", "1" and "2", respectively, and will be available in a custom template like
  10. // "mycheckbox_0", "mycheckbox_1" and "mycheckbox_2".
  11. // label controls will be automatically created having the names "label_mycheckbox_0", "label_mycheckbox_1" and
  12. // "label_mycheckbox_2" (label + underscore + control name + underscore + value with anything else other than
  13. // letters and numbers replaced with underscores - also, note that multiple consecutive underscores will be
  14. // replaced by a single one)
  15. // $obj is a reference to the first checkbox
  16. $obj $form->add('checkboxes''mycheckbox',
  17.     array(
  18.         'Value 1',
  19.         'Value 2',
  20.         'Value 3'
  21.     )
  22. );
  24. // multiple checkboxes with specific indexes
  25. // checkboxes values will be "v1", "v2" and "v3", respectively, and will be available in a custom template like
  26. // "mycheckbox_v1", "mycheckbox_v2" and "mycheckbox_v3".
  27. // label controls will be automatically created having the names "label_mycheckbox_v1", "label_mycheckbox_v2" and
  28. // "label_mycheckbox_v3" (label + underscore + control name + underscore + value with anything else other than
  29. // letters and numbers replaced with underscores - also, note that multiple consecutive underscores will be
  30. // replaced by a single one)
  31. $obj $form->add('checkboxes''mycheckbox',
  32.     array(
  33.         'v1' => 'Value 1',
  34.         'v2' => 'Value 2',
  35.         'v3' => 'Value 3'
  36.     )
  37. );
  39. // multiple checkboxes with preselected value
  40. // "Value 2" will be the preselected value
  41. // note that for preselecting values you must use the actual indexes of the values, if available, (like
  42. // in the current example) or the default, zero-based index, otherwise (like in the next example)
  43. $obj $form->add('checkboxes''mycheckbox',
  44.     array(
  45.         'v1'    =>  'Value 1',
  46.         'v2'    =>  'Value 2',
  47.         'v3'    =>  'Value 3'
  48.     ),
  49.     'v2'    // note the index!
  50. );
  52. // "Value 2" will be the preselected value.
  53. // note that for preselecting values you must use the actual indexes of the values, if available, (like
  54. // in the example above) or the default, zero-based index, otherwise (like in the current example)
  55. $obj $form->add('checkboxes''mycheckbox',
  56.     array(
  57.         'Value 1',
  58.         'Value 2',
  59.         'Value 3'
  60.     ),
  61.     1    // note the index!
  62. );
  64. // multiple checkboxes with multiple preselected values
  65. $obj $form->add('checkboxes''mycheckbox[]',
  66.     array(
  67.         'v1'    =>  'Value 1',
  68.         'v2'    =>  'Value 2',
  69.         'v3'    =>  'Value 3'
  70.     ),
  71.     array('v1''v2')
  72. );
  74. // custom classes (or other attributes) can also be added to all of the elements by specifying a 4th argument;
  75. // this needs to be specified in the same way as you would by calling <a href="../Generic/Zebra_Form_Control.html#methodset_attributes">set_attributes()</a> method:
  76. $obj $form->add('checkboxes''mycheckbox[]',
  77.     array(
  78.         '1' =>  'Value 1',
  79.         '2' =>  'Value 2',
  80.         '3' =>  'Value 3',
  81.     ),
  82.     ''// no default value
  83.     array('class' => 'my_custom_class')
  84. );
  86. // don't forget to always call this method before rendering the form
  87. if ($form->validate()) {
  88.     // put code here
  89. }
  91. // output the form using an automatically generated template
  92. $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.

$id needs to be suffixed with square brackets if there are more checkboxes sharing the same name, so that PHP treats them as an array!

The control's name attribute will be as indicated by $id argument while the control's id attribute will be $id, stripped of square brackets (if any), followed by an underscore and followed by $value with all the spaces replaced by underscores.

So, if the $id arguments is "my_checkbox" and the $value argument is "value 1", the control's id attribute will be my_checkbox_value_1.

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 to be used in custom template files, in order to display the control.

  1. // in a template file, in order to print the generated HTML
  2. // for a control named "my_checkbox" and having the value of "value 1",
  3. // one would use:
  4. echo $my_checkbox_value_1;

Note that when adding the required rule to a group of checkboxes (checkboxes sharing the same name), it is sufficient to add the rule to the first checkbox!

mixed $value Value of the checkbox.
array $attributes

(Optional) An array of attributes valid for input controls (disabled, readonly, style, etc)

Must be specified as an associative array, in the form of attribute => value.

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

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:

type, id, name, value, class


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