@author Stefan Gabos
/**
* Adds a CAPTCHA image to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <b>You must also place a {@link Zebra_Form_Text textbox} control on the form and set the "captcha" rule to it!
* (through {@link set_rule()})</b>
*
* Properties of the CAPTCHA image can be altered by editing the file includes/captcha.php.
*
* By default, captcha values are triple md5 hashed and stored in cookies, and when the user enters the captcha
* value the value is also triple md5 hashed and the two values are then compared. Sometimes, your users may have
* a very restrictive cookie policy and so cookies will not be set, and therefore they will never be able to get
* past the CAPTCHA control. If it's the case, call the {@link Zebra_Form::captcha_storage() captcha_storage}
* method and set the storage method to "session".
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* // add a CAPTCHA image
* $form->add('captcha', 'my_captcha', 'my_text');
*
* // add a label for the textbox
* $form->add('label', 'label_my_text', 'my_text', 'Are you human?');
*
* // add a CAPTCHA to the form
* $obj = $form->add('text', 'my_text');
*
* // set the "captcha" rule to the textbox
* $obj->set_rule(array(
* 'captcha' => array('error', 'Characters not entered correctly!')
* ));
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* This is the name of the variable to be used in the template file, containing
* the generated HTML for the control.
*
* <code>
* // in a template file, in order to print the generated HTML
* // for a control named "my_captcha", one would use:
* echo $my_captcha;
* </code>
*
* @param string $attach_to The <b>id</b> attribute of the {@link Zebra_Form_Text textbox} control to attach
* the CAPTCHA image to.
*
* @return void
*/
function __construct($id, $attach_to, $storage = 'cookie')
{
// call the constructor of the parent class
parent::__construct();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('disable_xss_filters', 'for', 'locked');
// set the default attributes for the text control
// put them in the order you'd like them rendered
$this->set_attributes(array('type' => 'captcha', 'name' => $id, 'id' => $id, 'for' => $attach_to));
}
/**
* Adds an <input type="submit"> control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* /**
* * add a submit control to the form
* * the "&" symbol is there so that $obj will be a reference to the object in PHP 4
* * for PHP 5+ there is no need for it
* {@*}
* $obj = &$form->add('submit', 'my_submit', 'Submit');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* The control's <b>name</b> attribute will be the same as the <b>id</b> attribute!
*
* This is the name to be used when referring to the control's value in the
* POST/GET superglobals, after the form was submitted.
*
* This is also the name of the variable to be used in the template file, containing
* the generated HTML for the control.
*
* <code>
* /**
* * in a template file, in order to print the generated HTML
* * for a control named "my_submit", one would use:
* {@*}
* echo $my_submit;
* </code>
*
* @param string $caption Caption of the submit button control.
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.4 input}
* controls (size, readonly, style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "alt" attribute
* $obj = &$form->add(
* 'submit',
* 'my_submit',
* 'Submit',
* array(
* 'alt' => 'Click to submit values'
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
* <b>type</b>, <b>id</b>, <b>name</b>, <b>value</b>, <b>class</b>
*
* @return void
*/
function Zebra_Form_Submit($id, $caption, $attributes = '')
{
// call the constructor of the parent class
parent::Zebra_Form_Control();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('disable_xss_filters', 'locked');
// set the default attributes for the submit button control
// put them in the order you'd like them rendered
$this->set_attributes(array('type' => 'submit', 'name' => $id, 'id' => $id, 'value' => $caption, 'class' => 'submit'));
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds an <input type="hidden"> control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* // add a hidden control to the form
* // the "&" symbol is there so that $obj will be a reference to the object in PHP 4
* // for PHP 5+ there is no need for it
* $obj = &$form->add('hidden', 'my_hidden', 'Secret value');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* The control's <b>name</b> attribute will be the same as the <b>id</b> attribute!
*
* This is the name to be used when referring to the control's value in the
* POST/GET superglobals, after the form is submitted.
*
* <b>Hidden controls are automatically rendered when the {@link Zebra_Form::render() render()}
* method is called!</b><br>
* <b>Do not print them in template files!</b>
*
* @param string $default (Optional) Default value of the text box.
*
* @return void
*/
function Zebra_Form_Hidden($id, $default = '')
{
// call the constructor of the parent class
parent::Zebra_Form_Control();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('disable_xss_filters', 'locked');
// set the default attributes for the hidden control
// put them in the order you'd like them rendered
// notice that if control's name is 'MAX_FILE_SIZE' we'll generate a random ID attribute for the control
// as, with multiple forms having upload controls on them, this hidden control appears as many times as the
// forms do and we don't want to have the same ID assigned to multiple controls
$this->set_attributes(array('type' => 'hidden', 'name' => $id, 'id' => $id != 'MAX_FILE_SIZE' ? $id : 'mfs_' . rand(0, 100000), 'value' => $default));
}
/**
* Adds an <textarea> control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* // add a textarea control to the form
* // the "&" symbol is there so that $obj will be a reference to the object in PHP 4
* // for PHP 5+ there is no need for it
* $obj = &$form->add('textarea', 'my_textarea');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* The control's <b>name</b> attribute will be the same as the <b>id</b> attribute!
*
* 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.
*
* <code>
* // in a template file, in order to print the generated HTML
* // for a control named "my_textarea", one would use:
* echo $my_textarea;
* </code>
*
* @param string $default (Optional) Default value of the textarea.
*
* @param array $attributes (Optional) An array of attributes valid for
* <b>{@link http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.7 textarea}</b>
* controls (rows, cols, style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "rows" attribute
* $obj = &$form->add(
* 'textarea',
* 'my_textarea',
* '',
* array(
* 'rows' => 10
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
*
* <b>id</b>, <b>name</b>, <b>class</b>
*
* @return void
*/
function Zebra_Form_Textarea($id, $default = '', $attributes = '')
{
// call the constructor of the parent class
parent::Zebra_Form_Control();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('default_value', 'disable_xss_filters', 'locked', 'type', 'value');
// set the default attributes for the textarea control
// put them in the order you'd like them rendered
$this->set_attributes(array('name' => $id, 'id' => $id, 'rows' => 5, 'cols' => '80', 'class' => 'control', 'type' => 'textarea', 'value' => $default));
// if "class" is amongst user specified attributes
if (isset($attributes['class'])) {
// we need to set the "class" attribute like this, so it doesn't overwrite previous values
$this->set_attributes(array('class' => $attributes['class']), false);
// make sure we don't set it again below
unset($attributes['class']);
}
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds an <input type="reset"> control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* // add a reset control to the form
* $obj = $form->add('reset', 'my_reset', 'Reset');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* The control's <b>name</b> attribute will be the same as the <b>id</b> attribute!
*
* 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.
*
* <code>
* // in a template file, in order to print the generated HTML
* // for a control named "my_reset", one would use:
* echo $my_reset;
* </code>
*
* @param string $caption Caption of the reset button control.
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.4 input}
* controls (size, readonly, style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "alt" attribute
* $obj = $form->add(
* 'reset',
* 'my_reset',
* 'Reset',
* array(
* 'alt' => 'Click to reset values'
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
* <b>type</b>, <b>id</b>, <b>name</b>, <b>value</b>, <b>class</b>
*
* @return void
*/
function __construct($id, $caption, $attributes = '')
{
// call the constructor of the parent class
parent::__construct();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('disable_xss_filters', 'locked');
// set the default attributes for the reset button control
// put them in the order you'd like them rendered
$this->set_attributes(array('type' => 'reset', 'name' => $id, 'id' => $id, 'value' => $caption, 'class' => 'reset'));
// if "class" is amongst user specified attributes
if (is_array($attributes) && isset($attributes['class'])) {
// we need to set the "class" attribute like this, so it doesn't overwrite previous values
$this->set_attributes(array('class' => $attributes['class']), false);
// make sure we don't set it again below
unset($attributes['class']);
}
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds an <input type="password"> control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* /**
* * add a password control to the form
* * the "&" symbol is there so that $obj will be a reference to the object in PHP 4
* * for PHP 5+ there is no need for it
* {@*}
* $obj = &$form->add('password', 'my_password');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* The control's <b>name</b> attribute will be the same as the <b>id</b> attribute!
*
* This is the name to be used when referring to the control's value in the
* POST/GET superglobals, after the form was submitted.
*
* This is also the name of the variable to be used in the template file, containing
* the generated HTML for the control.
*
* <code>
* /**
* * in a template file, in order to print the generated HTML
* * for a control named "my_password", one would use:
* {@*}
* echo $my_password;
* </code>
*
* @param string $default (Optional) Default value of the password field.
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.4 input}
* controls (size, readonly, style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "disabled" attribute
* $obj = &$form->add(
* 'password',
* 'my_password',
* '',
* array(
* 'disabled' => 'disabled'
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
*
* <b>type</b>, <b>id</b>, <b>name</b>, <b>value</b>, <b>class</b>
*
* @return void
*/
function Zebra_Form_Password($id, $default = '', $attributes = '')
{
// call the constructor of the parent class
parent::Zebra_Form_Control();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('default_value', 'disable_xss_filters', 'locked');
// set the default attributes for the button control
$this->set_attributes(array('type' => 'password', 'name' => $id, 'id' => $id, 'value' => $default, 'class' => 'control password'));
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds a time picker control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* The output of this control will be one, two, three or four {@link Zebra_Form_Select select} controls for hour,
* minutes, seconds and AM/PM respectively, according to the given format as set by the <i>$attributes</i> argument.
*
* Note that even though there will be more select boxes, the submitted values will be available as a single merged
* value (in the form of hh:mm:ss AM/PM, depending on the format), with the name as given by the <i>id</i> argument.
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* // add a time picker control for hour and minutes
* $obj = $form->add('time', 'my_time', date('H:i'), array('format' => 'hm'));
*
* // don't forget to always call this method before rendering the form
* if ($form->validate()) {
*
* // note that even though there will be more select boxes, the submitted
* // values will be available as a single merged value (in the form of
* // mm:mm:ss AM/PM, depending on the format), with the name as given by
* // the "id" argument:
* echo $_POST['my_time'];
*
* }
*
* // output the form using an automatically generated template
* $form->render();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* The control's <b>name</b> attribute will be the same as the <b>id</b> attribute!
*
* 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.
*
* <code>
* // in a template file, in order to print the generated HTML
* // for a control named "my_time", one would use:
* echo $my_time;
* </code>
*
* @param string $default (Optional) String representing the default time to be shown. Must be set according
* to the format of the time, as specified in <i>$attributes</i>. For example, for a
* time format of "hm", one would set the default time in the form of "hh:mm" while
* for a time format of "hms", one would set the time in the form of "hh:mm:ss".
*
* Default is current system time.
*
* @param array $attributes (Optional) An array of user specified attributes valid for an time picker
* control (format, hours, minutes, seconds, am/pm).
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
*
* Available attributes are:
*
* - format - format of time; a string containing one, or a combination of the four
* allowed characters: "h" (hours), "m" (minutes) and "s" (seconds) and "g" for
* using 12-hours format instead of the default 23-hours format; (i.e. setting the
* format to "hm" would allow the selection of hours and minutes, setting the
* format to "hms" would allow the selection of hours, minutes and seconds, and
* setting the format to "hmg" would allow the selection of hours and minutes
* using the 12-hours format instead of the 24-hours format)
*
* - hours - an array of selectable hours (i.e. array(10, 11, 12))
*
* - minutes - an array of selectable minutes (i.e. array(15, 30, 45))
*
* - seconds - an array of selectable seconds
*
* See {@link Zebra_Form_Control::set_attributes() set_attributes()} on how to set
* attributes, other than through the constructor.
*
* @return void
*/
function __construct($id, $default = '', $attributes = '')
{
// call the constructor of the parent class
parent::__construct();
// these will hold the default selectable hours, minutes and seconds
$hours = $minutes = $seconds = array();
// all the 24 hours are available by default
for ($i = 0; $i < 24; $i++) {
$hours[] = $i;
}
// all the minutes and seconds are available by default
for ($i = 0; $i < 60; $i++) {
$minutes[] = $seconds[] = $i;
}
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('disable_xss_filters', 'locked', 'type', 'name', 'id', 'format', 'hours', 'minutes', 'seconds', 'value');
// set the default attributes for the text control
// put them in the order you'd like them rendered
$this->set_attributes(array('type' => 'time', 'name' => $id, 'id' => $id, 'value' => $default, 'class' => 'control time', 'format' => 'hm', 'hours' => $hours, 'minutes' => $minutes, 'seconds' => $seconds));
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds a "note" to the form, attached to a control.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* /**
* * add a text control to the form
* * the "&" symbol is there so that $obj will be a reference to the object in PHP 4
* * for PHP 5+ there is no need for it
* {@*}
* $obj = &$form->add('text', 'my_text');
*
* // attach a note to the textbox control
* $form->add('none', 'note_my_text', 'my_text', 'Enter some text in the field above');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* This is the name of the variable to be used in the template file, containing
* the generated HTML for the control.
*
* <code>
* /**
* * in a template file, in order to print the generated HTML
* * for a control named "my_note", one would use:
* {@*}
* echo $my_note;
* </code>
*
* @param string $attach_to The <b>id</b> attribute of the control to attach the note to.
*
* <i>Notice that this must be the "id" attribute of the control you are attaching
* the label to, and not the "name" attribute!</i>
*
* This is important as while most of the controls have their <b>id</b> attribute
* set to the same value as their <b>name</b> attribute, for {@link Zebra_Form_Checkbox checkboxes},
* {@link Zebra_Form_Select selects} and {@link Zebra_Form_Radio radio buttons} this
* is different.
*
* <b>Exception to the rule:</b>
*
* Just like in the case of {@link Zebra_Form_Label labels}, if you want a <b>master</b>
* note, a note that is attached to a <b>group</b> of checkboxes/radio buttons rather than
* individual controls, this attribute must instead refer to the <b>name</b> of the
* controls (which, for groups of checkboxes/radio buttons, is one and the same).
*
* @param string $caption Content of the note (can be both plain text and/or HTML)
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/struct/global.html#h-7.5.4 div}
* elements (style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "style" attribute
* $obj = &$form->add(
* 'note',
* 'note_my_text',
* 'my_text',
* array(
* 'style' => 'width:250px'
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
* <b>class</b>
*
* @return void
*/
function Zebra_Form_Note($id, $attach_to, $caption, $attributes = '')
{
// call the constructor of the parent class
parent::Zebra_Form_Control();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
$this->private_attributes = array('caption', 'disable_xss_filters', 'locked', 'for', 'name', 'type');
// set the default attributes for the HTML control
$this->set_attributes(array('class' => 'note', 'caption' => $caption, 'for' => $attach_to, 'id' => $id, 'name' => $id, 'type' => 'note'));
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Add an <label> control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* // add a label, attached to a textbox control
* $form->add('label', 'label_my_text', 'my_text', 'Enter some text:');
*
* // add a text control to the form
* $obj = $form->add('text', 'my_text');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* This is the name of the variable to be used in the template file, containing
* the generated HTML for the control.
*
* <code>
* // in a template file, in order to print the generated HTML
* // for a control named "my_label", one would use:
* echo $my_label;
* </code>
*
* @param string $attach_to The <b>id</b> attribute of the control to attach the note to.
*
* <i>Notice that this must be the "id" attribute of the control you are attaching
* the label to, and not the "name" attribute!</i>
*
* This is important as while most of the controls have their <b>id</b> attribute
* set to the same value as their <b>name</b> attribute, for {@link Zebra_Form_Checkbox checkboxes},
* {@link Zebra_Form_Select selects} and {@link Zebra_Form_Radio radio buttons} this
* is different.
*
* <b>Exception to the rule:</b>
*
* Just like in the case of {@link Zebra_Form_Note notes}, if you want a <b>master</b>
* label, a label that is attached to a <b>group</b> of checkboxes/radio buttons
* rather than individual controls, this attribute must instead refer to the <b>name</b>
* of the controls (which, for groups of checkboxes/radio buttons, is one and the same).
* This is important because if the group of checkboxes/radio buttons have the
* <i>required</i> rule set, this is the only way in which the "required" symbol
* (the red asterisk) will be attached to the master label instead of being attached
* to the first checkbox/radio button from the group.
*
* @param mixed $caption Caption of the label.
*
* <i>Putting a $ (dollar) sign before a character will turn that specific character into
* the accesskey.</i><br>
* <i>If you need the dollar sign in the label, escape it with</i> \ <i>(backslash)</i>
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/interact/forms.html#edef-LABEL label}
* elements (style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "style" attribute
* $obj = $form->add(
* 'label',
* 'label_my_text',
* 'my_text',
* 'My Label:'
* array(
* 'style' => 'font-weight: normal'
* )
* );
* </code>
*
* <b>Special attribute:</b>
*
* When setting the special attribute <b>inside</b> to <b>true</b>, the label will
* appear inside the control is attached to (if the control the label is attached to
* is a {@link Zebra_Form_Text textbox} or a {@link Zebra_Form_Textarea textarea}) and
* will disappear when the control will receive focus. When the "inside" attribute is
* set to TRUE, the label will not be available in the template file as it will be
* contained by the control the label is attached to!
*
* <code>
* $form->add('label', 'my_label', 'my_control', 'My Label:', array('inside' => true));
* </code>
*
* <samp>Sometimes, when using floats, the inside-labels will not be correctly positioned
* as jQuery will return invalid numbers for the parent element's position; If this is
* the case, make sure you enclose the form in a div with position:relative to fix
* this issue.</samp>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
* <b>id</b>, <b>for</b>
*
* @return void
*/
function __construct($id, $attach_to, $caption, $attributes = '')
{
// call the constructor of the parent class
parent::__construct();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
$this->private_attributes = array('disable_xss_filters', 'for_group', 'inside', 'label', 'locked', 'name', 'type');
// set the default attributes for the label
$this->set_attributes(array('for' => $attach_to, 'id' => $id, 'label' => $caption, 'name' => $id, 'type' => 'label'));
// sets user specified attributes for the table cell
$this->set_attributes($attributes);
}
/**
* Adds a "note" to the form, attached to a control.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* // add a text control to the form
* $obj = $form->add('text', 'my_text');
*
* // attach a note to the textbox control
* $form->add('note', 'note_my_text', 'my_text', 'Enter some text in the field above');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* This is the name of the variable to be used in the template file, containing
* the generated HTML for the control.
*
* <code>
* // in a template file, in order to print the generated HTML
* // for a control named "my_note", one would use:
* echo $my_note;
* </code>
*
* @param string $attach_to The <b>id</b> attribute of the control to attach the note to.
*
* <i>Notice that this must be the "id" attribute of the control you are attaching
* the label to, and not the "name" attribute!</i>
*
* This is important as while most of the controls have their <b>id</b> attribute
* set to the same value as their <b>name</b> attribute, for {@link Zebra_Form_Checkbox checkboxes},
* {@link Zebra_Form_Select selects} and {@link Zebra_Form_Radio radio buttons} this
* is different.
*
* <b>Exception to the rule:</b>
*
* Just like in the case of {@link Zebra_Form_Label labels}, if you want a <b>master</b>
* note, a note that is attached to a <b>group</b> of checkboxes/radio buttons rather than
* individual controls, this attribute must instead refer to the <b>name</b> of the
* controls (which, for groups of checkboxes/radio buttons, is one and the same).
*
* @param string $caption Content of the note (can be both plain text and/or HTML)
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/struct/global.html#h-7.5.4 div}
* elements (style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "style" attribute
* $obj = $form->add(
* 'note',
* 'note_my_text',
* 'my_text',
* array(
* 'style' => 'width:250px'
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
* <b>class</b>
*
* @return void
*/
function __construct($id, $attach_to, $caption, $attributes = '')
{
// call the constructor of the parent class
parent::__construct();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
$this->private_attributes = array('caption', 'disable_xss_filters', 'locked', 'for', 'name', 'type');
// set the default attributes for the HTML control
$this->set_attributes(array('class' => 'note', 'caption' => $caption, 'for' => $attach_to, 'id' => $id, 'name' => $id, 'type' => 'note'));
// if "class" is amongst user specified attributes
if (is_array($attributes) && isset($attributes['class'])) {
// we need to set the "class" attribute like this, so it doesn't overwrite previous values
$this->set_attributes(array('class' => $attributes['class']), false);
// make sure we don't set it again below
unset($attributes['class']);
}
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds a date control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* The output of this control will be a {@link Zebra_Form_Text textbox} control with an icon to the right of it.<br>
* Clicking the icon will open an inline JavaScript date picker.<br>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* // add a date control to the form
* $mydate = $form->add('date', 'my_date', date('Y-m-d'));
*
* // you *have* to set the "date" rule
* $mydate->set_rule(array(
* 'date' => array('error', 'Invalid date specified!'),
* ));
*
* // set the date's format
* $mydate->format('M d, Y');
*
* // don't forget to always call this method before rendering the form
* if ($form->validate()) {
*
* // get the date in YYYY-MM-DD format so you can play with is easily
* $date = $mydate->get_date();
*
* }
*
* // output the form using an automatically generated template
* $form->render();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* The control's <b>name</b> attribute will be the same as the <b>id</b> attribute!
*
* 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.
*
* <code>
* // in a template file, in order to print the generated HTML
* // for a control named "my_date", one would use:
* echo $my_date;
* </code>
*
* @param string $default (Optional) Default date, formatted according to {@link format() format}.
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.4 input}
* controls (size, readonly, style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "readonly" attribute
* $obj = $form->add(
* 'date',
* 'my_date',
* '',
* array(
* 'readonly' => 'readonly'
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
*
* <b>type</b>, <b>id</b>, <b>name</b>, <b>value</b>, <b>class</b>
*
* @return void
*/
function __construct($id, $default = '', $attributes = '')
{
// call the constructor of the parent class
parent::__construct();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('locked', 'disable_xss_filters', 'disable_zebra_datepicker', 'date', 'always_visible', 'days', 'days_abbr', 'direction', 'disabled_dates', 'enabled_dates', 'first_day_of_week', 'format', 'header_captions', 'header_navigation', 'inside_icon', 'lang_clear_date', 'months', 'months_abbr', 'offset', 'pair', 'readonly_element', 'show_clear_date', 'show_other_months', 'show_select_today', 'show_week_number', 'select_other_months', 'start_date', 'strict', 'view', 'weekend_days', 'zero_pad');
// set the javascript attributes of this control
// these attributes will be used by the JavaScript date picker object
$this->javascript_attributes = array('always_visible', 'days', 'days_abbr', 'direction', 'disabled_dates', 'enabled_dates', 'first_day_of_week', 'format', 'header_captions', 'header_navigation', 'inside_icon', 'lang_clear_date', 'months', 'months_abbr', 'offset', 'pair', 'readonly_element', 'show_clear_date', 'show_other_months', 'show_select_today', 'show_week_number', 'select_other_months', 'start_date', 'strict', 'view', 'weekend_days', 'zero_pad');
// set the default attributes for the text control
// put them in the order you'd like them rendered
$this->set_attributes(array('type' => 'text', 'name' => $id, 'id' => $id, 'value' => $default, 'class' => 'control text date', 'always_visible' => null, 'days' => null, 'days_abbr' => null, 'direction' => null, 'disable_zebra_datepicker' => false, 'disabled_dates' => null, 'enabled_dates' => null, 'first_day_of_week' => null, 'format' => 'Y-m-d', 'header_captions' => null, 'header_navigation' => null, 'inside_icon' => null, 'months' => null, 'months_abbr' => null, 'offset' => null, 'pair' => null, 'readonly_element' => null, 'show_clear_date' => null, 'show_other_months' => null, 'show_select_today' => null, 'show_week_number' => null, 'select_other_months' => null, 'start_date' => null, 'strict' => null, 'view' => null, 'weekend_days' => null, 'zero_pad' => null));
// if "class" is amongst user specified attributes
if (is_array($attributes) && isset($attributes['class'])) {
// we need to set the "class" attribute like this, so it doesn't overwrite previous values
$this->set_attributes(array('class' => $attributes['class']), false);
// make sure we don't set it again below
unset($attributes['class']);
}
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds an <textarea> control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* /**
* * add a textarea control to the form
* * the "&" symbol is there so that $obj will be a reference to the object in PHP 4
* * for PHP 5+ there is no need for it
* {@*}
* $obj = &$form->add('textarea', 'my_textarea');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* The control's <b>name</b> attribute will be the same as the <b>id</b> attribute!
*
* This is the name to be used when referring to the control's value in the
* POST/GET superglobals, after the form was submitted.
*
* This is also the name of the variable to be used in the template file, containing
* the generated HTML for the control.
*
* <code>
* /**
* * in a template file, in order to print the generated HTML
* * for a control named "my_textarea", one would use:
* {@*}
* echo $my_textarea;
* </code>
*
* @param string $default (Optional) Default value of the textarea.
*
* @param array $attributes (Optional) An array of attributes valid for
* <b>{@link http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.7 textarea}</b>
* controls (rows, cols, style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "rows" attribute
* $obj = &$form->add(
* 'textarea',
* 'my_textarea',
* '',
* array(
* 'rows' => 10
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
*
* <b>id</b>, <b>name</b>, <b>class</b>
*
* @return void
*/
function Zebra_Form_Textarea($id, $default = '', $attributes = '')
{
// call the constructor of the parent class
parent::Zebra_Form_Control();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('default_value', 'disable_xss_filters', 'locked', 'type', 'value');
// set the default attributes for the textarea control
// put them in the order you'd like them rendered
$this->set_attributes(array('name' => $id, 'id' => $id, 'rows' => 5, 'cols' => '80', 'class' => 'control', 'type' => 'textarea', 'value' => $default));
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds an <input type="checkbox"> control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* // single checkbox
* // the "&" symbol is there so that $obj will be a reference to the object in PHP 4
* // for PHP 5+ there is no need for it
* $obj = &$form->add('checkbox', 'my_checkbox', 'my_checkbox_value');
*
* // multiple checkboxes
* // notice that is "checkboxes" instead of "checkbox"
* // checkboxes values will be "0", "1" and "2", respectively, and will be available in a custom template like
* // "mycheckbox_0", "mycheckbox_1" and "mycheckbox_2".
* // label controls will be automatically created having the names "label_mycheckbox_0", "label_mycheckbox_1" and
* // "label_mycheckbox_2" (label + underscore + control name + underscore + value with anything else other than
* // letters and numbers replaced with an underscore)
* // $obj is a reference to the first checkbox
* $obj = &$form->add('checkboxes', 'mycheckbox',
* array(
* 'Value 1',
* 'Value 2',
* 'Value 3'
* )
* );
*
* // multiple checkboxes with specific indexes
* // checkboxes values will be "v1", "v2" and "v3", respectively, and will be available in a custom template like
* // "mycheckbox_v1", "mycheckbox_v2" and "mycheckbox_v3".
* // label controls will be automatically created having the names "label_mycheckbox_v1", "label_mycheckbox_v2" and
* // "label_mycheckbox_v3" (label + underscore + control name + underscore + value with anything else other than
* // letters and numbers replaced with an underscore)
* $obj = &$form->add('checkboxes', 'mycheckbox',
* array(
* 'v1' => 'Value 1',
* 'v2' => 'Value 2',
* 'v3' => 'Value 3'
* )
* );
*
* // multiple checkboxes with preselected value
* // "Value 2" will be the preselected value
* // note that for preselecting values you must use the actual indexes of the values, if available, (like
* // in the current example) or the default, zero-based index, otherwise (like in the next example)
* $obj = &$form->add('checkboxes', 'mycheckbox',
* array(
* 'v1' => 'Value 1',
* 'v2' => 'Value 2',
* 'v3' => 'Value 3'
* ),
* 'v2' // note the index!
* );
*
* // "Value 2" will be the preselected value.
* // note that for preselecting values you must use the actual indexes of the values, if available, (like
* // in the example above) or the default, zero-based index, otherwise (like in the current example)
* $obj = &$form->add('checkboxes', 'mycheckbox',
* array(
* 'Value 1',
* 'Value 2',
* 'Value 3'
* ),
* 1 // note the index!
* );
*
* // multiple checkboxes with multiple preselected values
* $obj = &$form->add('checkboxes', 'mycheckbox[]',
* array(
* 'v1' => 'Value 1',
* 'v2' => 'Value 2',
* 'v3' => 'Value 3'
* ),
* array('v1', 'v2')
* );
*
* // custom classes (or other attributes) can also be added to all of the elements by specifying a 4th argument;
* // this needs to be specified in the same way as you would by calling {@link set_attributes()} method:
* $obj = &$form->add('checkboxes', 'mycheckbox[]',
* array(
* '1' => 'Value 1',
* '2' => 'Value 2',
* '3' => 'Value 3',
* ),
* '', // no default value
* array('class' => 'my_custom_class')
* );
*
* // 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();
* </code>
*
* <samp>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
* {@link Zebra_Form_Control::disable_spam_filter() disable_spam_filter()} method to prevent that from happening!</samp>
*
* @param string $id Unique name to identify the control in the form.
*
* <b>$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!</b>
*
* The control's <b>name</b> attribute will be as indicated by <i>$id</i>
* argument while the control's <b>id</b> attribute will be <i>$id</i>, stripped of
* square brackets (if any), followed by an underscore and followed by <i>$value</i>
* with all the spaces replaced by <i>underscores</i>.
*
* So, if the <i>$id</i> arguments is "my_checkbox" and the <i>$value</i> argument
* is "value 1", the control's <b>id</b> attribute will be <b>my_checkbox_value_1</b>.
*
* 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.
*
* <code>
* // in a template file, in order to print the generated HTML
* // for a control named "my_checkbox" and having the value of "value 1",
* // one would use:
* echo $my_checkbox_value_1;
* </code>
*
* <i>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!</i>
*
* @param mixed $value Value of the checkbox.
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.4 input}
* controls (disabled, readonly, style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "checked" attribute
* $obj = &$form->add(
* 'checkbox',
* 'my_checkbox',
* 'v1',
* array(
* 'checked' => 'checked'
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
*
* <b>type</b>, <b>id</b>, <b>name</b>, <b>value</b>, <b>class</b>
*
* @return void
*/
function Zebra_Form_Checkbox($id, $value, $attributes = '')
{
// call the constructor of the parent class
parent::Zebra_Form_Control();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('disable_spam_filter', 'disable_xss_filters', 'locked');
// set the default attributes for the checkbox control
// put them in the order you'd like them rendered
$this->set_attributes(array('type' => 'checkbox', 'name' => $id, 'id' => str_replace(array(' ', '[', ']'), array('_', ''), $id) . '_' . str_replace(' ', '_', $value), 'value' => $value, 'class' => 'control checkbox'));
// if "class" is amongst user specified attributes
if (isset($attributes['class'])) {
// we need to set the "class" attribute like this, so it doesn't overwrite previous values
$this->set_attributes(array('class' => $attributes['class']), false);
// make sure we don't set it again below
unset($attributes['class']);
}
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds a date control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* The output of this control will be a {@link Zebra_Form_Text textbox} control with an icon to the right of it.<br>
* Clicking the icon will open an inline JavaScript date picker.<br>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* /**
* * add a date control to the form
* * the "&" symbol is there so that $obj will be a reference to the object in PHP 4
* * for PHP 5+ there is no need for it
* {@*}
* $obj = &$form->add('date', 'my_date', date('Y-m-d'));
*
* // set the date's format
* $obj->format('Y-m-d');
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* The control's <b>name</b> attribute will be the same as the <b>id</b> attribute!
*
* This is the name to be used when referring to the control's value in the
* POST/GET superglobals, after the form was submitted.
*
* This is also the name of the variable to be used in the template file, containing
* the generated HTML for the control.
*
* <code>
* /**
* * in a template file, in order to print the generated HTML
* * for a control named "my_date", one would use:
* {@*}
* echo $my_date;
* </code>
*
* @param string $default (Optional) Default date, formatted according to {@link format() format}.
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.4 input}
* controls (size, readonly, style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "readonly" attribute
* $obj = &$form->add(
* 'date',
* 'my_date',
* '',
* array(
* 'readonly' => 'readonly'
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
*
* <b>type</b>, <b>id</b>, <b>name</b>, <b>value</b>, <b>class</b>
*
* @return void
*/
function Zebra_Form_Date($id, $default = '', $attributes = '')
{
// call the constructor of the parent class
parent::Zebra_Form_Control();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('locked', 'disable_xss_filters', 'date');
// set the javascript attributes of this control
// these attributes will be used by the JavaScript date picker object
$this->javascript_attributes = array('days', 'direction', 'disabled_dates', 'first_day_of_week', 'format', 'months', 'offset', 'readonly_element', 'view', 'weekend_days');
// set the default attributes for the text control
// put them in the order you'd like them rendered
$this->set_attributes(array('type' => 'text', 'name' => $id, 'id' => $id, 'value' => $default, 'class' => 'control text date', 'days' => null, 'direction' => null, 'disabled_dates' => null, 'first_day_of_week' => null, 'format' => 'Y-m-d', 'months' => null, 'offset' => null, 'readonly_element' => null, 'view' => null, 'weekend_days' => null));
// sets user specified attributes for the control
$this->set_attributes($attributes);
}
/**
* Adds an <input type="checkbox"> control to the form.
*
* <b>Do not instantiate this class directly! Use the {@link Zebra_Form::add() add()} method instead!</b>
*
* <code>
* // create a new form
* $form = new Zebra_Form('my_form');
*
* /**
* * single checkbox
* * the "&" symbol is there so that $obj will be a reference to the object in PHP 4
* * for PHP 5+ there is no need for it
* {@*}
* $obj = &$form->add('checkbox', 'my_checkbox', 'my_checkbox_value');
*
* /**
* * multiple checkboxes
* * notice that is "checkboxes" instead of "checkbox"
* * label controls will be automatically created having the names "more_checkboxes_value_1",
* * "more_checkboxes_value_2" and so on
* * $obj is a reference to the first checkbox
* * checkboxes values will be "0", "1" and "2", respectively
* {@*}
* $obj = &$form->add('checkboxes', 'more_checkboxes',
* array(
* 'Value 1',
* 'Value 2',
* 'Value 3'
* )
* );
*
* /**
* * multiple checkboxes with specific indexes
* * checkboxes values will be "v1", "v2" and "v3", respectively
* * label controls will be automatically created having the names "some_more_checkboxes_value_1",
* * "some_more_checkboxes_value_2" and so on
* {@*}
* $obj = &$form->add('checkboxes', 'some_more_checkboxes',
* array(
* 'v1' => 'Value 1',
* 'v2' => 'Value 2',
* 'v3' => 'Value 3'
* )
* );
*
* /**
* * multiple checkboxes with preselected value
* * "Value 2" will be the preselected value
* * note that for preselecting values you must use the actual indexes of the values, if available, (like
* * in the current example) or the default, zero-based index, otherwise (like in the next example)
* * label controls will be automatically created having the names "and_some_more_checkboxes_value_v1",
* * "and_some_more_checkboxes_value_v2" and so on
* {@*}
* $obj = &$form->add('checkboxes', 'and_some_more_checkboxes',
* array(
* 'v1' => 'Value 1',
* 'v2' => 'Value 2',
* 'v3' => 'Value 3'
* ),
* 'v2' // note the index!
* );
*
* /**
* * "Value 2" will be the preselected value.
* * note that for preselecting values you must use the actual indexes of the values, if available, (like
* * in the example above) or the default, zero-based index, otherwise (like in the current example)
* * label controls will be automatically created having the names "and_some_more_checkboxes_value_0",
* * "and_some_more_checkboxes_value_1" and so on
* {@*}
* $obj = &$form->add('checkboxes', 'and_some_more_checkboxes',
* array(
* 'Value 1',
* 'Value 2',
* 'Value 3'
* ),
* 1 // note the index!
* );
*
* /**
* * multiple checkboxes with multiple preselected values
* {@*}
* $obj = &$form->add('checkboxes', 'other_checkboxes[]',
* array(
* 'v1' => 'Value 1',
* 'v2' => 'Value 2',
* 'v3' => 'Value 3'
* ),
* array('v1', 'v2')
* );
*
* // 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();
* </code>
*
* @param string $id Unique name to identify the control in the form.
*
* <b>$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!</b>
*
* The control's <b>name</b> attribute will be as indicated by <i>$id</i>
* argument while the control's <b>id</b> attribute will be <i>$id</i>, stripped of
* square brackets (if any), followed by an underscore and followed by <i>$value</i>
* with all the spaces replaced by <i>underscores</i>.
*
* So, if the <i>$id</i> arguments is "my_checkbox" and the <i>$value</i> argument
* is "value 1", the control's <b>id</b> attribute will be <b>my_checkbox_value_1</b>.
*
* This is the name to be used when referring to the control's value in the
* POST/GET superglobals, after the form was submitted.
*
* This is also the name of the variable to be used in the template file, containing
* the generated HTML for the control.
*
* <code>
* /**
* * in a template file, in order to print the generated HTML
* * for a control named "my_checkbox" and having the value of "value 1",
* * one would use:
* {@*}
* echo $my_checkbox_value_1;
* </code>
*
* <i>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!</i>
*
* @param mixed $value Value of the checkbox.
*
* @param array $attributes (Optional) An array of attributes valid for
* {@link http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.4 input}
* controls (disabled, readonly, style, etc)
*
* Must be specified as an associative array, in the form of <i>attribute => value</i>.
* <code>
* // setting the "checked" attribute
* $obj = &$form->add(
* 'checkbox',
* 'my_checkbox',
* 'v1',
* array(
* 'checked' => 'checked'
* )
* );
* </code>
*
* See {@link Zebra_Form_Control::set_attributes() 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:<br>
*
* <b>type</b>, <b>id</b>, <b>name</b>, <b>value</b>, <b>class</b>
*
* @return void
*/
function Zebra_Form_Checkbox($id, $value, $attributes = '')
{
// call the constructor of the parent class
parent::Zebra_Form_Control();
// set the private attributes of this control
// these attributes are private for this control and are for internal use only
// and will not be rendered by the _render_attributes() method
$this->private_attributes = array('disable_xss_filters', 'locked');
// set the default attributes for the checkbox control
// put them in the order you'd like them rendered
$this->set_attributes(array('type' => 'checkbox', 'name' => $id, 'id' => str_replace(array(' ', '[', ']'), array('_', ''), $id) . '_' . str_replace(' ', '_', $value), 'value' => $value, 'class' => 'control checkbox'));
// sets user specified attributes for the control
$this->set_attributes($attributes);
}