Public Member Functions | |
| __construct () | |
| Initialize a new AnewtForm instance. | |
| setup ($id=null, $method=null, $action=null) | |
| Setup the form in one step. | |
Getter and setter methods | |
| get_method_as_string () | |
| Return the form method as a string. | |
Methods for getting and setting form values | |
| fill ($values) | |
| Fill form using the supplied values. | |
| autofill () | |
| Fill form automatically from query data. | |
| get_control_value ($name) | |
| Get the value of a control. | |
| set_control_value ($name, $value) | |
| Set the value of a control. | |
| get_control_values () | |
| Retrieve all form values. | |
Form processing methods | |
| process () | |
| Process this form. | |
| handle_valid () | |
| Callback when form validation was succesful. | |
| handle_invalid () | |
| Callback when form validation did not succeed. | |
Validation methods | |
| is_valid () | |
| Checks whether the form is completely valid. | |
Private Attributes | |
| $_children = array() | |
| Numeric array to hold all children of this form. | |
| $_controls_by_name = array() | |
| Associative array to hold all form controls by name. | |
| $_fieldsets_by_name = array() | |
| Associative array to hold all form fieldsets by name. | |
| $_hidden_controls = array() | |
| List of references to hidden controls. | |
Methods for controls and other form elements | |
| add_control ($control) | |
| Add a control to this form. | |
| add_hidden_control ($name, $value) | |
| Easily add a hidden control to this form. | |
| add_fieldset ($fieldset) | |
| Add a fieldset to this form. | |
| add_node ($node) | |
| Add a custom node to this form. | |
| has_control ($name) | |
| Check whether a control with this name already exists. | |
| get_control ($name) | |
| Get a reference to a control. | |
| get_fieldset ($name) | |
| Get a reference to a fieldset. | |
| _hidden_controls () | |
| Return hidden form controls. | |
| _contains_file_upload_control () | |
| Check whether this form contains a file upload control (or a derived control). | |
| _children () | |
| Return all children on this form as a list. | |
This class can be used to create an XHTML form. An AnewtForm instance holds a number of controls, fieldset or custom XHTML elements. Additionally, it has a few properties that influence its behaviour:
id property is the form idmethod is either ANEWT_FORM_METHOD_GET or ANEWT_FORM_METHOD_POST action is the URL the form will be posted toUsually an AnewtForm subclass is created. The constructor of this subclass adds controls to the form, and optionally the handle_valid() and handle_invalid() methods are overridden. Calling code then instantiates this subclass, fills it with values using fill() or autofill(), then processes the form using process().
Definition at line 39 of file form.lib.php.
| AnewtForm::__construct | ( | ) |
Initialize a new AnewtForm instance.
Do not forget to call this method when you override the constructor in a subclass, i.e. call parent::__construct().
Definition at line 67 of file form.lib.php.
| AnewtForm::setup | ( | $ | id = null, |
|
| $ | method = null, |
|||
| $ | action = null | |||
| ) |
Setup the form in one step.
This is just a convenience method, any of the arguments are optional.
| $id | Id of the form | |
| $method | Form method; must be one of the ANEWT_FORM_METHOD_GET or ANEWT_FORM_METHOD_POST constants | |
| $action | The url to post this form to |
Definition at line 94 of file form.lib.php.
| AnewtForm::get_method_as_string | ( | ) |
Return the form method as a string.
Definition at line 127 of file form.lib.php.
| AnewtForm::fill | ( | $ | values | ) |
Fill form using the supplied values.
This will iterate over all controls of the form and set their value accordingly (if any).
The return value can be used to determine whether a form was completely filled using the provided data, or that some values were missing from the $values array. See autofill() for more information about this.
| $values | Associative array used as a name to value mapping. |
true if the form was succesfully and completely using the provided $values, false otherwise.Definition at line 165 of file form.lib.php.
| AnewtForm::autofill | ( | ) |
Fill form automatically from query data.
If the form uses the GET method the data comes from $_GET. If the form uses the POST method the data comes from $_POST.
The return value (see also fill() for an explanation) can be used to detect incomplete $_GET or $_POST values. This may happen when handling different form flavours with different controls using a single form, e.g. a simple and advanced search form pointing to the same page in which an instance of the advanced flavour of the form handles the submitted data. It may also happen when users are messing with the submitted data. You may then decide to process() the form only if all values were provided. Example: if ($form->autofill() && $form->process()) { ...} else { ...}
$_GET or $_POST, false if this was not the case.Definition at line 197 of file form.lib.php.
| AnewtForm::get_control_value | ( | $ | name | ) |
Get the value of a control.
The specified control must exist.
This method takes into account whether a control is empty and optional, in which case NULL is returned. For this reason, the value as returned by this method may differ from the value obtained using get('value') on the control instance itself, which always returns the ‘real’ control value. (This is because you can change the required property afterwards, so trying to be smart is not what we want there.)
| $name | The name of the control |
Definition at line 231 of file form.lib.php.
| AnewtForm::set_control_value | ( | $ | name, | |
| $ | value | |||
| ) |
Set the value of a control.
The specified control must exist.
| $name | The name of the control | |
| $value | The value to set |
Definition at line 257 of file form.lib.php.
| AnewtForm::get_control_values | ( | ) |
Retrieve all form values.
See AnewtForm::get_control_value for a description of the values returned by this method, which may contain NULL in some cases.
Definition at line 275 of file form.lib.php.
| AnewtForm::process | ( | ) |
Process this form.
This will validate the form and all controls, and call either handle_valid() or handle_invalid() depending on the validation results. The return value of the handle_valid() or handle_invalid() function is returned to the caller of this method.
If the handle_valid() and handle_invalid() methods are not overridden true and false are returned, respectively. This allows calling code to use something like this: if ($form->process()) { ... } else { ... }
Definition at line 312 of file form.lib.php.
| AnewtForm::handle_valid | ( | ) |
Callback when form validation was succesful.
This method returns true. You may override this method in subclasses.
Definition at line 325 of file form.lib.php.
| AnewtForm::handle_invalid | ( | ) |
Callback when form validation did not succeed.
This method returns false. You may override this method in subclasses.
Definition at line 335 of file form.lib.php.
| AnewtForm::is_valid | ( | ) |
Checks whether the form is completely valid.
This iterates over all controls and checks their validity as well.
Definition at line 354 of file form.lib.php.
| AnewtForm::add_control | ( | $ | control | ) |
Add a control to this form.
| $control | The form control instance to add |
Definition at line 384 of file form.lib.php.
| AnewtForm::add_hidden_control | ( | $ | name, | |
| $ | value | |||
| ) |
Easily add a hidden control to this form.
This is a convenience method to easily add a hidden form control to this form. It is exactly the same as creating an AnewtFormControlHidden instance manually and adding to the form using AnewtForm::add_control
| $name | The name of the control | |
| $value | The hidden value |
Definition at line 417 of file form.lib.php.
| AnewtForm::add_fieldset | ( | $ | fieldset | ) |
Add a fieldset to this form.
| $fieldset | The fieldset instance to add |
Definition at line 430 of file form.lib.php.
| AnewtForm::add_node | ( | $ | node | ) |
Add a custom node to this form.
This node is directly embedded in the rendered output by form renderers.
| $node | An AnewtXMLDomNode to embed in the form. |
Definition at line 457 of file form.lib.php.
| AnewtForm::has_control | ( | $ | name | ) |
Check whether a control with this name already exists.
| $name | The name of the control |
Definition at line 472 of file form.lib.php.
| AnewtForm::get_control | ( | $ | name | ) |
Get a reference to a control.
The control must exist for this function to work.
| $name | The name of the control |
Definition at line 489 of file form.lib.php.
| AnewtForm::get_fieldset | ( | $ | name | ) |
Get a reference to a fieldset.
The fieldset must exist for this function to work.
| $name | The name of the fieldset |
Definition at line 507 of file form.lib.php.
| AnewtForm::_children | ( | ) | [protected] |
Return all children on this form as a list.
This method is intended for form renderer implementations only.
Definition at line 524 of file form.lib.php.
| AnewtForm::_hidden_controls | ( | ) |
Return hidden form controls.
This method is intended for form renderer implementations only.
Definition at line 537 of file form.lib.php.
| AnewtForm::_contains_file_upload_control | ( | ) |
Check whether this form contains a file upload control (or a derived control).
This is useful to find out which enctype the form should have.
This method is intended for form renderer implementations only.
Set a special flag in add_control instead of using this method
Definition at line 554 of file form.lib.php.
1.5.9