Package: Controls

Class: Zebra_Form_Checkbox

source file: /includes/Checkbox.php

Class Overview

XSS_Clean
|
--Zebra_Form_Control
|
--Zebra_Form_Checkbox

Class for checkbox controls.

Author(s):

Copyright:

  • (c) 2006 - 2013 Stefan Gabos

Methods

Inherited properties

Class: Zebra_Form_Control

Zebra_Form_Control::$attributes
Zebra_Form_Control::$private_attributes
Zebra_Form_Control::$rules

Inherited methods

Class: Zebra_Form_Control

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

Class: XSS_Clean

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

$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
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