HTML form logic. More...

Public Member Functions
	__construct ($id, $form_def, Toolbox $toolbox, $form_flags=0)
	Create form described by $form_def using $toolbox. More...

	setId ($id)
	Set form ID. More...

	getToken ()
	Get token for this form (simple helper).

	getFieldGroups ()
	Retrieve field groups.

	setDefaults ($custom_defaults, $group=null)
	Set custom default values. More...

	getValues ()
	Returns values submitted by user.

	setCollectionKey ($group, $key)
	Set collection key. More...

	getCollectionKey ($group)
	Retrieve collection key for given group. More...

	unsetCollectionKey ($group)
	Unset collection key. More...

	getViewData ($group, $field=null)
	Get data for a view. More...

	getRawData ($group, $field=null)
	Get raw data for HTML form field. More...

	loadInput ($raw_input=null)
	Load submitted input. More...

	useDefaults ()
	Sets form to use default values.

	useInput ()
	Sets form to use user submitted values.

	isSubmitted ()
	Returns true when form is submitted. More...

	isValid ()
	Returns true when all data are valid. More...

	setFieldError ($group_id, $field_id, $error, $args=true)
	Assign error to field.

	getFieldErrors ($group_id, $field_id)
	Get all errors assigned to a field.

	getHtmlFieldId ($group, $field, $field_component=null)
	Helper method to get correct HTML form field ID.

	getHtmlFieldName ($group, $field, $field_component=null)
	Helper method to get correct HTML form field name.

	getAllFieldGroups ()
	Get field definitions.

	getFieldGroup ($group)
	Get field group definition.

	getFieldGroupOption ($group, $option)
	Get field group option.

	getField ($group, $field)
	Get field definition.

	render ($template_engine=null)
	Render form using specified renderers.

	renderRootWidget ($template_engine)
	Start widget tree rendering.

	renderWidget ($template_engine, $widget_conf)
	Render a widget using given configuration. More...

	renderWidgets ($template_engine, $widget_conf_list)
	Helper method to render list of widgets.

	renderField ($template_engine, $group_id, $field_id, $renderer)
	Helper method to render a field widget. More...

Static Public Member Functions
static	createFormToken ($form_id)
	Generate form token for partial XSRF protection and form identification. More...

static	validateFormToken ($token, $form_id)
	Validate form token. More...

Public Attributes
	$id
	Global form ID (HTML attribute)

	$form_ttl = 750
	XSRF protection window (15 minutes by default)

	$action_url = ''
	Form target URL (empty = the same page)

	$target_form_id = null
	Specify target form when action_url is specified (this form may have different ID on another URL).

	$http_method = 'post'
	Form submit method.

	$readonly = false
	Is form a read-only view ?

	$html_class
	HTML class attribute (array of 'form', 'view', or anything else)

	$field_errors = array()
	Errors from all fields; 2D structure (group, field).

	$form_errors = array()
	Global errors; simple list.

Static Protected Member Functions
static	getFormTokenExtras ()
	Get some additional client-specific values to make hash more secure and bound to client. More...

Protected Attributes
	$toolbox
	Listing of all available tools to build forms. Fields, layouts, helpers, etc.

	$form_def
	Definition of the form. What fields in what layouts.

	$field_defaults = array()
	Default values used if form is not submitted. (single item dimension)

	$field_values = null
	Current value of the field (array, but it will be created very late).

	$raw_input = null
	Submitted input from user. Data are not modified in any way.

	$raw_defaults = array()
	Preprocessed default values. These data go directly to HTML form.

	$use_defaults = false
	Use default (true) or submitted (false) values.

	$group_keys = array()
	Group keys used for accessing fields in collections.

Errors
const	E_FORM_EXPIRED = 'form_expired'
	Error: The XSRF token has expired.

const	E_FORM_FIELD_ERROR = 'form_field_error'
	Error: Form contains field with error.

const	E_FIELD_REQUIRED = 'field_required'
	Error: The empty field is required.

const	E_FIELD_MALFORMED = 'field_malformed'
	Error: The field value is malformed (does not match pattern or so). More...

Form flags
const	READ_ONLY = 0x0001
	Form must be read only.

Detailed Description

HTML form logic.

Form lifetime:

A. Form is not submitted:

Initialize form – load definition.
Process input (empty for now).
Load default values.
Set form to use default values.
Show form.

B. Form is submitted:

Initialize form – load definition.
Process input (submission is detected).
Validate user input. 4a. If input is not valid, set form to use submitted values and show the form. 4b. Otherwise pass values to application.

Note: Please note that isSubmitted() does not mean that form data are valid. And also isValid() does not mean that form has been submitted. It is possible to get submitted form with invalid data as well as non-submitted form with valid data (for example filtering form).

/

Todo:: Both field value preprocessor and postprocessor must be methods of single class, because they must match together.

Constructor & Destructor Documentation

__construct	(		$id,
			$form_def,
		Toolbox	$toolbox,
			$form_flags = `0`
	)

Create form described by $form_def using $toolbox.

Parameters

$id	is form id. You can set $id to null here and set it later using setId().
$form_def	is the form definition.
$toolbox	is Toolbox used for form rendering.
$form_flags	is bitmap of [Form flags].

Member Function Documentation

setId ( $id )

Set form ID.

Use if ID cannot be set in constructor.

static createFormToken ( $form_id )

static

Generate form token for partial XSRF protection and form identification.

Returns: String value suitable for hidden <input>.

See also: validateFormToken()

static getFormTokenExtras ( )

staticprotected

Get some additional client-specific values to make hash more secure and bound to client.

Returned value must be constant as long as token should be valid.

/

Todo:: Add some secret and session-specific token to make it really hard to guess.

       @return Array of values, keys does not matter.

static validateFormToken	(	$token,
		$form_id
	)

static

Validate form token.

Returns: If validation is successful, returns time when token has been generated. Otherwise returns FALSE.

See also: createFormToken()

setDefaults	(	$custom_defaults,
		$group = `null`
	)

Set custom default values.

Does array_merge() definition defaults with custom defaults.

$custom_defaults has the same structure as values returned by getValues(), if $group is null. Otherwise $custom_defaults is only fragment for specified field group.

setCollectionKey	(	$group,
		$key
	)

Set collection key.

This key will be used to access particular item when accessing group field.

Parameters

$group	is field group id which is beiing iterated.
$key	is collection key (current index). Use array for multidimensional collections.

See also: unsetCollectionKey(), getCollectionKey(), getRawData()

getCollectionKey ( $group )

Retrieve collection key for given group.

Parameters

$group is field group id which is beiing iterated.

See also: setCollectionKey(), unsetCollectionKey(), getRawData()

unsetCollectionKey ( $group )

Unset collection key.

It is a good idea to unset the key after group is rendered to allow error detection.

Parameters

$group is field group id which is beiing iterated.

See also: setCollectionKey(), getCollectionKey(), getRawData()

getViewData	(	$group,
		$field = `null`
	)

Get data for a view.

Like getRawData(), but without processing, because view needs to display the real data.

Default values specified in field configuration are ignored.

Use this in @view renderer.

getRawData	(	$group,
		$field = `null`
	)

Get raw data for HTML form field.

Use this in @edit renderer.

loadInput ( $raw_input = null )

Load submitted input.

It is possible to use different input than $_GET or $_POST to make testing easy. If $raw_input is null, appropriate superglobal variable is used.

isSubmitted ( )

Returns true when form is submitted.

Data may not be valid.

isValid ( )

Returns true when all data are valid.

The form may not be submitted.

Validation is done by getValues(), which is called automatically by this method.

See also

renderWidget	(	$template_engine,
		$widget_conf
	)

Render a widget using given configuration.

Key #! determines renderer which will render the widget.

renderField	(	$template_engine,
		$group_id,
		$field_id,
		$renderer
	)

Helper method to render a field widget.

/

Todo:: Refactor renderWidget since fields are not ordinary widgets.

Member Data Documentation

const E_FIELD_MALFORMED = 'field_malformed'

Error: The field value is malformed (does not match pattern or so).

Public Member Functions

Static Public Member Functions

Public Attributes

Static Protected Member Functions

Protected Attributes

Errors

Form flags

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation