Public Member Functions
	pullField (&$record, &$field, &$form, $formFieldName, $new=false)
	pushField (&$record, &$field, &$form, $formFieldName, $new=false)
	pushValue (&$record, &$field, &$form, &$element, &$metaValues)
&	buildWidget (&$record, &$field, &$form, $formFieldName, $new=false, $permissions=null)
	registerWidgetHandler ($widgetType, $path, $class)
	unregisterWidgetHandler ($widgetType)
&	getWidgetHandler ($widgetType)
	_file_exists_incpath ($file)
	_formGroupExists (&$form, $group)
&	getElement (&$form, &$field, $name)
	groupFields (&$fields)
	_compareGroups ($g1, $g2)
	display (&$form, $template=null, $singleField=false, $useTabs=false)
	_sortTabs ($a, $b)
	createRecordForm (&$record, $new=false, $tab=null, $query=null)
	decorateRecordForm (&$record, &$form, $new=false, $tab=null)
	validateRecordForm (&$record, &$form, $new=false, $tab=null)
	handleTabSubmit (&$record, &$form, $tab=null)
	createHTMLTabs (&$record, &$form, $selectedTab)
	getSessionKey ()
	getSessionData ($tab=null, $session_key=null)
	clearSessionData ($session_key=null)
	storeSessionData ($data, $tab, $session_key=null, $record_id=null)
	createRecordButtons (&$record, $currentTab=null)
	saveSession (&$record, $new=false, $session_key=null)
Static Public Member Functions
static &	getInstance ()
static &	factory ()
static &	getVocabulary (&$record, &$field)
static	getVocabularyClasses (&$record, &$field)
static	_getVocabAndClasses (&$record, &$field)
Data Fields
	$widgetHandlerPaths = array()
	$widgetHandlerClasses = array()
	$widgetHandlers = array()

Detailed Description

A class encapsulating the most common form building and processing functions in dataface.

Author:: Steve Hannah <shannah@sfu.ca> May 2007

Definition at line 12 of file FormTool.php.

Member Function Documentation

_compareGroups	(	$	g1,
		$	g2
	)

Definition at line 851 of file FormTool.php.

_file_exists_incpath ( $ file )

Check if a file exists in the include path

Version:: 1.2.1

Author:: Aidan Lister <aidan@php.net> string $file Name of the file to look for mixed The full path if file exists, FALSE if it does not

Definition at line 681 of file FormTool.php.

_formGroupExists	(	&$	form,
		$	group
	)

Checks to see if a field group exists in a given form. This refers to a group in the sense of an HTML_QuickForm_group element and not the Dataface notion of a 'group' widget.

Parameters:

HTML_QuickForm	&$form	The form to check.
string	$group	The name of the group.

Returns:: boolean True if the group exists, otherwise false.

Definition at line 708 of file FormTool.php.

static _getVocabAndClasses	(	&$	record,
		&$	field
	)		`[static]`

Reutrns a 2-element array of arrays, containing both the classes and values for a valuelist.

Parameters:

Dataface_Record	&$record	The record being edited.
array	&$field	The field config array.

Returns:: array

Definition at line 631 of file FormTool.php.

_sortTabs	(	$	a,
		$	b
	)

Definition at line 946 of file FormTool.php.

& buildWidget	(	&$	record,
		&$	field,
		&$	form,
		$	formFieldName,
		$	new = `false`,
		$	permissions = `null`
	)

Parameters:

Dataface_Record	&$record	The Dataface Record that this widget is to be editing.
array	&$field	The field definition.
	HTML_QuickForm	The form to which the widget will be added.
string	$formFieldName	The name of the field on the form.

Returns:: HTML_QuickForm_element

Definition at line 409 of file FormTool.php.

clearSessionData ( $ session_key = null )

Clears the session data for the tab current form. This does not clear the session data for the entire session, just this form.

Parameters:

string $session_key The session key that is being cleared. Null for current key.

Returns:: void

Definition at line 1294 of file FormTool.php.

createHTMLTabs	(	&$	record,
		&$	form,
		$	selectedTab
	)

Creates an data-structure representing the tabs that can be displayed for a record form.

Parameters:

Dataface_Record	&$record	The record that is being edited.
HTML_QuickForm	&$form	The form that we are creating the tabs for.
string	$selectedTab	The name of the tab that is currently selected.

Returns:: array Datastructure of the form: array( array( // Tab 1 'url' => ... // URL for the tab. 'css_class' => ... // The CSS class that should be used for the tab. ), array( ... // Tab 2 ), ... );

Definition at line 1212 of file FormTool.php.

createRecordButtons	(	&$	record,
		$	currentTab = `null`
	)

Creates and HTML_QuickForm group that can be added a a QuickForm object to serve as the submit buttons for edit (or new record) forms. By default this will create buttons for each tab, a back, next, and save buttons.

CSS is used to hide the tabs by default.

Returns:: array(HTML_QuickForm_element) An array of submit elements.

Definition at line 1335 of file FormTool.php.

createRecordForm	(	&$	record,
		$	new = `false`,
		$	tab = `null`,
		$	query = `null`
	)

Builds an HTML_QuickForm object to edit the given record.

Parameters:

Dataface_Record	&$record	The record that is to be edited.
string	$tab	The name of the tab to display. In the case of multi tab forms, we may specify the tab which we wish to display. the tab may contain only a subset of the fields in the table, or it could be a 'partition' tab. A 'partition' tab.

Definition at line 961 of file FormTool.php.

decorateRecordForm	(	&$	record,
		&$	form,
		$	new = `false`,
		$	tab = `null`
	)

Adds the necessary extra fields to a form to equip it to be used to edit the given record. In particular, it adds the next, submit, etc.. buttons to the bottom of the form. It also adds a __keys__ group to store/submit the keys of the record so that the correct record is processed when the form is submitted.

Parameters:

Dataface_Record	&$record	The record that the form is to edit.
HTML_QuickForm	&$form	The form that is to be decorated.
boolean	$new	Whether we should treat this as a new record form.
string	$tab	The name of the tab that we are rendering (in the case of a multi-tab form).

Returns:: void

Definition at line 997 of file FormTool.php.

display	(	&$	form,
		$	template = `null`,
		$	singleField = `false`,
		$	useTabs = `false`
	)

Displays a form.

Parameters:

HTML_QuickForm	&$form	The form to be displayed.
string	$template	An alternate template that can be used to display the form.
string	$singleField	Optional name of a single field to be rendered. if this is the case, then only one field from the form will be rendered and it will include a javascript onblur handler to auto save as soon as the user leaves the field.

Returns:: void

Definition at line 871 of file FormTool.php.

static& factory ( ) [static]

Returns a QuickForm object that can be used to generate elements safely.

Definition at line 583 of file FormTool.php.

& getElement	(	&$	form,
		&$	field,
		$	name
	)

Gets an element from a form.

Parameters:

HTML_QuickForm	&$form	The form from which the element is being retrieved.
array	&$field	The field config array for the field in question.
string	$name	The name of the field.

Returns:: HTML_QuickForm_element

Definition at line 725 of file FormTool.php.

static& getInstance ( ) [static]

Singleton method for obtaining a reference to the Dataface_FormTool object.

Definition at line 32 of file FormTool.php.

getSessionData	(	$	tab = `null`,
		$	session_key = `null`
	)

Returns an associative array of the session data, either for the current tab or for all tabs.

Parameters:

string	$tab	The name of the tab that we wish to get data for. If this is left null, it will return all tabs data.
string	$session_key	The session key. If this is left null, it will return data for the current session.

Returns:: array Associative array of session data, as it was submitted in the forms. The data structure looks like: array( 'tabs' => array( 'tab1' => array( 'myfield1' => 'val1', ... etc ... ), 'tab2' => array( 'myfieldx' => 'valx' ... etc ... ), ... ) )

Definition at line 1270 of file FormTool.php.

getSessionKey ( )

Returns the key that is used to keep track of this particular session. This manifests itself as the $_GET['--form-session-key'] variable. If no session key is set, this will generate a new one and add a '--form-session-key' variable to the current $query.

Returns:: The current session key.

Definition at line 1234 of file FormTool.php.

static& getVocabulary	(	&$	record,
		&$	field
	)		`[static]`

Gets a vocabulary that can be used in a particular field.

Parameters:

Dataface_Record	&$record	The record that is being edited.
array	&$field	The config array for the field.

Returns:: array The associative array of options in the valuelist.

Definition at line 600 of file FormTool.php.

static getVocabularyClasses	(	&$	record,
		&$	field
	)		`[static]`

Gets the list of meta values that is associated with the valuelist for a particular field. The idea is that the options in a valuelist can be categorized into classes. This returns those classes.

Parameters:

Dataface_Record	&$record	The record that is being edited.
array	&$field	The config array for the field being edited.

Returns:: array The associative array of classes [key => class]

Definition at line 615 of file FormTool.php.

& getWidgetHandler ( $ widgetType )

Obtains a reference to the widget handler object for a particular type of widget.

Parameters:

string $widgetType The name of the type of widget to be handled.

Returns:: The widget handler.

Definition at line 546 of file FormTool.php.

groupFields ( &$ fields )

Groups a collection of fields together by group.

Parameters:

array &$fields associative array of field config arrays.

Returns:: array

Definition at line 803 of file FormTool.php.

handleTabSubmit	(	&$	record,
		&$	form,
		$	tab = `null`
	)

Handles form submission for the given form. It handles multi-tab forms and even sends an HTTP redirect to the correct tab upon submission, if the action requested was to go to a different tab.

This uses the special --session:target:xyz POST variables to see which tab is being submitted.

Parameters:

	Dataface_Record	The record to be edited.
	HTML_QuickForm	The form that is submitted.
string	$tab	The name of the tab that has been submitted.

Returns:: void

Definition at line 1109 of file FormTool.php.

pullField	(	&$	record,
		&$	field,
		&$	form,
		$	formFieldName,
		$	new = `false`
	)

Pulls the data from the underlying $record object into the field.

Parameters:

Dataface_Record	&$record	The Dataface_Record object from which the data is being pulled.
array	&$field	The field configuration array for the field being pulled.
HTML_QuickForm	&$form	The form that is pulling the data.
string	$formFieldName	The name of the field within the form.
boolean	$new	Whether or not this is a new record form. In this case default values will be used.

Returns:: mixed PEAR_Error if there is an error. or true on success.

Definition at line 57 of file FormTool.php.

pushField	(	&$	record,
		&$	field,
		&$	form,
		$	formFieldName,
		$	new = `false`
	)

Pushes data from a form widget into a Dataface_Record object.

Parameters:

Dataface_Record	&$record	The record into which the data is being pushed.
array	&$field	The field configuration array as loaded from the fields.ini file.
HTML_QuickForm	&$form	The form from which the data is being taken.
string	$formFieldName	The name of the field in the form.
boolean	$new	Whether this is a new record form.

Returns:: mixed PEAR_Error if there is an error. true on success.

Definition at line 169 of file FormTool.php.

pushValue	(	&$	record,
		&$	field,
		&$	form,
		&$	element,
		&$	metaValues
	)

Extracts value from the form ready to be stored in the table. This doesn't actually push the data into the record, only obtains the data ready to be pushed.

Parameters:

Dataface_Record	&$record	The record into which the data is meant to be pushed.
HTML_QuickForm	&$form	The form from which the data is taken.
	HTML_QuickForm_element	The element (i.e. widget) from which the data is taken.
array	&$metaValues	An associative array of meta values in case there are other fields that should be filled in based on the data in this field.

Returns:: mixed The value that is to be pushed in the record.

Definition at line 311 of file FormTool.php.

registerWidgetHandler	(	$	widgetType,
		$	path,
		$	class
	)

Registers a class to handle the pushing and pulling for a particular type of widget.

Parameters:

string	$widgetType	The name of the widget type being registered. e.g. file, text, checkbox
string	$path	The path to the file containing the class.
string	$class	The name of the class.

Returns:: void

Definition at line 522 of file FormTool.php.

saveSession	(	&$	record,
		$	new = `false`,
		$	session_key = `null`
	)

Now that we allow tabbed forms, we may be temporarily storing data in the session. This goes through the session data and saves it to the appropriate places

Definition at line 1388 of file FormTool.php.

storeSessionData	(	$	data,
		$	tab,
		$	session_key = `null`,
		$	record_id = `null`
	)

Stores data from a form session so that it can be retrieved in the next page or the next time a tab is loaded for this form.

If we are using a multi-tab implementation, then we need to store the data for each tab in sessions until we are ready to save the entire record.

Definition at line 1308 of file FormTool.php.

unregisterWidgetHandler ( $ widgetType )

Unregisters a particular widget handler.

See also:: registerWidgetHandler()

Definition at line 532 of file FormTool.php.

validateRecordForm	(	&$	record,
		&$	form,
		$	new = `false`,
		$	tab = `null`
	)

Validates a form to see if it is ready to be processed.

Parameters:

Dataface_Record	&$record	The record that is being edited with this form.
	HTML_QuickForm	The form that is to be validated.
boolean	$new	Whether this form is creating a new record.
string	$tab	The name of the tab that is being processed.

Returns:: boolean True if the form validates.

Definition at line 1052 of file FormTool.php.

Field Documentation

$widgetHandlerClasses = array()

The classes for handling widgets.

Definition at line 21 of file FormTool.php.

$widgetHandlerPaths = array()

The paths to the widget handler files.

Definition at line 17 of file FormTool.php.

$widgetHandlers = array()

Cache for instantiated widget handler objects.

Definition at line 26 of file FormTool.php.

The documentation for this class was generated from the following file:

Dataface/FormTool.php

Public Member Functions

Static Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

Field Documentation