AnewtForm class

Basic form class.

Page Contents

  1. Class Overview
  2. Public Methods
  3. Getter and setter methods
  4. Methods for getting and setting form values
  5. Form processing methods
  6. Validation methods
  7. Methods for controls and other form elements
  8. Private Attributes
  9. Inheritance

Class Overview

Basic form class.

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:

Usually 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().

Todo

Reference module documentation once it's written.

Public Methods

__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().

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.

Parameters

$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

Getter and setter methods

get_method_as_string()

Return the form method as a string.

Return value

Form method as string, either GET or POST.

Methods for getting and setting form values

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.

Parameters

$values

Associative array used as a name to value mapping.

Return value

true if the form was succesfully and completely using the provided $values, false otherwise.

See also

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 { ...}

Return value

True if this fill could be automatically filled from $_GET or $_POST, false if this was not the case.

See also

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.)

Parameters

$name

The name of the control

Return value

The value of the control

See also

set_control_value($name, $value)

Set the value of a control.

The specified control must exist.

Parameters

$name

The name of the control

$value

The value to set

See also

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.

Return value

Associative array with all form control values by control name.

See also

Form processing methods

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 { ... }

Return value

Return value from handle_valid() or handle_invalid();

See also

handle_valid()

Callback when form validation was succesful.

This method returns true. You may override this method in subclasses.

handle_invalid()

Callback when form validation did not succeed.

This method returns false. You may override this method in subclasses.

Validation methods

is_valid()

Checks whether the form is completely valid.

This iterates over all controls and checks their validity as well.

Return value

True if valid, false otherwise

Methods for controls and other form elements

add_control($control)

Add a control to this form.

Parameters

$control

The form control instance to add

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

Parameters

$name

The name of the control

$value

The hidden value

See also

add_fieldset($fieldset)

Add a fieldset to this form.

Parameters

$fieldset

The fieldset instance to add

add_node($node)

Add a custom node to this form.

This node is directly embedded in the rendered output by form renderers.

Parameters

$node

An AnewtXMLDomNode to embed in the form.

has_control($name)

Check whether a control with this name already exists.

Parameters

$name

The name of the control

Return value

Boolean indicating Whether the control exists

get_control($name)

Get a reference to a control.

The control must exist for this function to work.

Parameters

$name

The name of the control

Return value

A reference to the control instance

get_fieldset($name)

Get a reference to a fieldset.

The fieldset must exist for this function to work.

Parameters

$name

The name of the fieldset

Return value

A reference to the AnewtFormFieldset instance

_hidden_controls()

Return hidden form controls.

This method is intended for form renderer implementations only.

Return value

Array of hidden form controls (may be empty)

_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.

Return value

True if the form contains a file upload control, false otherwise.

Todo

Implement AnewtFormControlFileUpload

Set a special flag in add_control instead of using this method

_children() [protected]

Return all children on this form as a list.

This method is intended for form renderer implementations only.

Return value

List of children, e.g. form control instances and fieldsets.

Private Attributes

$_children [private]

Numeric array to hold all children of this form.

$_controls_by_name [private]

Associative array to hold all form controls by name.

$_fieldsets_by_name [private]

Associative array to hold all form fieldsets by name.

$_hidden_controls [private]

List of references to hidden controls.

Inheritance

Base Classes

Inherited members

Anewt. Almost No Effort Web Toolkit.

© 2006–2009. This page was generated at 2009-08-02T22:54:43+02:00.