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

Public Member Functions
	pullField ($record, &$field, $form, $formFieldName, $new=false)
	Pulls the data from the underlying $record object into the field. This method will obtain it's value from the following mechanisms in order:
	pushField ($record, &$field, $form, $formFieldName, $new=false)
	Pushes data from a form widget into a Dataface_Record object. This will try to delegate to the following mechanisms if found:
	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.
&	buildWidget ($record, &$field, $form, $formFieldName, $new=false, $permissions=null)
	Builds a widget that can be added to a form. This will delegate to the WidgetHandler::buildWidget() method if defined for the field's widget type.
	registerWidgetHandler ($widgetType, $path, $class)
	Registers a class to handle the pushing and pulling for a particular type of widget. This is the mechanism by which custom widgets can be created and registered. All that is required is to define a WidgetHandler and then register that handler with the form tool with this method.
	unregisterWidgetHandler ($widgetType)
	Unregisters a particular widget handler.
&	getWidgetHandler ($widgetType)
	Obtains a reference to the widget handler object for a particular type of widget.
&	getElement (&$form, &$field, $name)
	Gets an element from a form.
	groupFields (&$fields)
	Groups a collection of fields together by group.
	display (&$form, $template=null, $singleField=false, $useTabs=false)
	Displays a form.
	createRecordForm ($record, $new=false, $tab=null, $query=null)
	Builds an HTML_QuickForm object to edit the given record.
	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.
	validateRecordForm ($record, &$form, $new=false, $tab=null)
	Validates a form to see if it is ready to be processed.
	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.
	createHTMLTabs ($record, $form, $selectedTab)
	Creates an data-structure representing the tabs that can be displayed for a record form.
	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.
	getSessionData ($tab=null, $session_key=null)
	Returns an associative array of the session data, either for the current tab or for all tabs.
	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.
	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.
	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.
	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.

Static Public Member Functions
static &	getInstance ()
	Singleton method for obtaining a reference to the Dataface_FormTool object.
static &	factory ()
	Returns a QuickForm object that can be used to generate elements safely.
static &	getVocabulary ($record, &$field)
	Gets a vocabulary that can be used in a particular field.
static	getVocabularyClasses ($record, &$field)
	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.

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 shann.nosp@m.ah@s.nosp@m.fu.ca May 2007

Definition at line 9 of file FormTool.php.

Member Function Documentation

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

Builds a widget that can be added to a form. This will delegate to the WidgetHandler::buildWidget() method if defined for the field's widget type.

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 437 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 1353 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 1271 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 1394 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 1020 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 1056 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 923 of file FormTool.php.

static& factory ( )

static

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

Definition at line 626 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 771 of file FormTool.php.

static& getInstance ( )

static

Singleton method for obtaining a reference to the Dataface_FormTool object.

Definition at line 29 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 1329 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 1293 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 643 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 658 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: WidgetHandler The widget handler.

Definition at line 589 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 852 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 1168 of file FormTool.php.

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

Pulls the data from the underlying $record object into the field. This method will obtain it's value from the following mechanisms in order:

WidgetHandler::pullField() if it exists (for the widget handler for the current widget type
DelegateClass::fieldname__pullValue() if it exists
WidgetHandler::pullValue() if it exists (for the widget handler for the current widget type).
Dataface_Record::getValueAsString() it is exists

The difference between this method and pullValue() is that this method will actually set the value into the widget, whereas pullValue() will only retrieve the value that should be set into the widget.

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.

See Also: WidgetHandler::pullField(); pullValue()

Definition at line 75 of file FormTool.php.

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

Pushes data from a form widget into a Dataface_Record object. This will try to delegate to the following mechanisms if found:

WidgetHandler::pushField() if it exists for the current widget type.
WidgetHandler::pushValue() if it exists for the current widget type.

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.

See Also: WidgetHandler::pushField(); pullField()

Definition at line 189 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.

This method will delegate to the WidgetHandler::pushValue() method of the field's widget if defined.

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 335 of file FormTool.php.

registerWidgetHandler	(	$widgetType,
		$path,
		$class
	)

Registers a class to handle the pushing and pulling for a particular type of widget. This is the mechanism by which custom widgets can be created and registered. All that is required is to define a WidgetHandler and then register that handler with the form tool with this method.

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

Example: $formTool = Dataface_FormTool::getInstance();

$formTool->registerWidgetHandler('colorpicker', '/path/to/my/colorpicker.php', 'my_colorpicker_class');

Definition at line 565 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 1448 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 1367 of file FormTool.php.

unregisterWidgetHandler ( $widgetType )

Unregisters a particular widget handler.

See Also: registerWidgetHandler()

Definition at line 575 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 1111 of file FormTool.php.

Field Documentation

$widgetHandlerClasses = array()

The classes for handling widgets.

Definition at line 18 of file FormTool.php.

$widgetHandlerPaths = array()

The paths to the widget handler files.

Definition at line 14 of file FormTool.php.

$widgetHandlers = array()

Cache for instantiated widget handler objects.

Definition at line 23 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