Class Alfresco.forms.Form

Class to represent the forms runtime.

Constructor Summary
Constructor Attributes	Constructor Name and Description
	Alfresco.forms.Form(formId) Constructor for a form.

Field Summary
Field Attributes	Field Name and Description
	ajaxSubmit Flag to determine whether the form will be submitted using an AJAX request.
	ajaxSubmitHandlers Object holding the callback handlers and messages for AJAX submissions.
	ajaxSubmitMethod String representing the http method to be used for the
	doBeforeAjaxRequest Object literal containing the abstract function for intercepting AJAX form submission.
	doBeforeFormSubmit Object literal containing the abstract function for pre-submission form processing.
	errorContainer String representing where errors should be displayed.
	formId HTML id of the form being represented.
	showSubmitStateDynamically Flag to determine whether the submit elements dynamically update
	showSubmitStateDynamicallyErrors Flag to determine whether any errors are shown when the dynamic
	submitAsJSON Flag to determine whether the form data should be submitted
	submitElements List of ids and/or elements being used to submit the form.
	validateAllOnSubmit Flag to indicate whether the form will validate all fields upon submission.
	validateOnSubmit Flag to indicate whether the form will validate upon submission, true
	validations List of validations to execute when the form is submitted.

Method Summary
Method Attributes	Method Name and Description
	addError(msg, field) Adds an error to the form.
	addSubmitElement(submitElement) Adds the given submitElement to the list of submit elements
	addValidation(fieldId, validationHandler, validationArgs, when, message) Adds validation for a specific field on the form.
	applyTabFix() Applies a Key Listener to input fields to ensure tabbing only targets elements
	getFieldLabel(fieldId) Retrieves the label text for a field
	getFormData() Retrieves the data currently held by the form.
	init() Sets up the required event handlers and prepares the form for use.
	setAJAXSubmit(ajaxSubmit, callbacks) Enables or disables whether the form submits via an AJAX call.
	setAjaxSubmitMethod(ajaxSubmitMethod) Set the http method to use for the AJAX call.
	setErrorContainer(position) Sets the container where errors will be displayed.
	setRepeatable(fieldId, containerId) Sets a field as being repeatable, this adds a 'plus' sign after the field
	setShowSubmitStateDynamically(showState, showErrors) Sets whether the submit elements dynamically update
	setSubmitAsJSON(submitAsJSON) Enables or disables submitting the form data in JSON format.
	setSubmitElements(submitElements) Sets the list of ids and/or elements being used to submit the form.
	setValidateAllOnSubmit(validate) Sets whether all fields are validated when the form is submitted.
	setValidateOnSubmit(validate) Enables or disables validation when the form is submitted.
	updateSubmitElements() Updates the state of all submit elements.

Constructor Detail

Alfresco.forms.Form(formId)

Constructor for a form.

Parameters:
{String} formId: The HTML id of the form to be managed

Returns:: {Alfresco.forms.Form} The new Form instance

Field Detail

{boolean} ajaxSubmit

Flag to determine whether the form will be submitted using an AJAX request.

{object} ajaxSubmitHandlers

Object holding the callback handlers and messages for AJAX submissions.
The callback handlers are themselves an object of the form:
fn: function, // The handler to call when the event fires.
obj: object, // An object to pass back to the handler.
scope: object // The object to use for the scope of the handler.

{String} ajaxSubmitMethod

String representing the http method to be used for the
ajax call. Default is POST.

{object} doBeforeAjaxRequest

Object literal containing the abstract function for intercepting AJAX form submission.
Returning false from the override will prevent the Forms Runtime from submitting the data.
fn: function, // The override function.
obj: object, // An object to pass back to the function.
scope: object // The object to use for the scope of the function.

{object} doBeforeFormSubmit

Object literal containing the abstract function for pre-submission form processing.
fn: function, // The override function.
obj: object, // An object to pass back to the function.
scope: object // The object to use for the scope of the function.

{string} errorContainer

String representing where errors should be displayed.
If the value is not "alert" it's presumed the string is the id of an
HTML object to be used as the error container.

{string} formId

HTML id of the form being represented.

{boolean} showSubmitStateDynamically

Flag to determine whether the submit elements dynamically update
their state depending on the current values in the form.

{boolean} showSubmitStateDynamicallyErrors

Flag to determine whether any errors are shown when the dynamic
submit state option is enabled.

{boolean} submitAsJSON

Flag to determine whether the form data should be submitted
represented by a JSON structure.

{object[]} submitElements

List of ids and/or elements being used to submit the form.

{boolean} validateAllOnSubmit

Flag to indicate whether the form will validate all fields upon submission.
The default is false which will stop after the first validation failure,
true will validate all fields and thus show all errors.

{boolean} validateOnSubmit

Flag to indicate whether the form will validate upon submission, true
by default.

{object[]} validations

List of validations to execute when the form is submitted.

Method Detail

addError(msg, field)

Adds an error to the form.

Parameters:
{string} msg: The error message to display
{object} field: The element representing the field the error occurred on

addSubmitElement(submitElement)

Adds the given submitElement to the list of submit elements
for the form.

Parameters:
submitElement: Object or string representing the submit element

addValidation(fieldId, validationHandler, validationArgs, when, message)

Adds validation for a specific field on the form.

Parameters:
{string} fieldId: Id of the field the validation is for
{function} validationHandler: Function to call to handle the
actual validation
{object} validationArgs: Optional object representing the
arguments to pass to the validation handler function
{string} when: Name of the event the validation should fire on
can be any event applicable for the field for example on a text
field "blur" can be used to fire the validation handler as the
user leaves the field. If null, the validation is only called
upon form submission
message: Message to be displayed when validation fails, if omitted
or null the default message in the handler is used

applyTabFix()

Applies a Key Listener to input fields to ensure tabbing only targets elements
that specifically set a "tabindex" attribute.
This has only been seen as an issue with the Firefox web browser, so shouldn't be applied otherwise.

{string} getFieldLabel(fieldId)

Retrieves the label text for a field

Parameters:
{string} fieldId: The id of the field to get the label for

Returns:: {string} The label for the field or the fieldId if a label could not be found

getFormData()

Retrieves the data currently held by the form.

Returns:: An object representing the form data

init()

Sets up the required event handlers and prepares the form for use.
NOTE: This must be called after all other setup methods.

setAJAXSubmit(ajaxSubmit, callbacks)

Enables or disables whether the form submits via an AJAX call.

Parameters:
{boolean} ajaxSubmit: true to submit using AJAX, false to submit
using the browser's default behaviour
{object} callbacks: Optional object representing callback handlers
or messages to use, for example
{
successCallback: yourHandlerObject,
failureCallback: yourHandlerObject,
successMessage: yourMessage,
failureMessage: yourMessage
}
Callback handler objects are of the form:
{
fn: function, // The handler to call when the event fires.
obj: object, // An object to pass back to the handler.
scope: object // The object to use for the scope of the handler.
}

setAjaxSubmitMethod(ajaxSubmitMethod)

Set the http method to use for the AJAX call.

Parameters:
{string} ajaxSubmitMethod: the http method to use for the AJAX call

setErrorContainer(position)

Sets the container where errors will be displayed.

Parameters:
{string} position: String representing where errors should
be displayed. If the value is not "alert" it's presumed the
string is the id of an HTML object to be used as the error
container

setRepeatable(fieldId, containerId)

Sets a field as being repeatable, this adds a 'plus' sign after the field
thus allowing multiple values to be entered.

Parameters:
{string} fieldId: Id of the field the validation is for
{string} containerId: Id of the element representing the
field 'prototype' i.e. the item that will get cloned.

setShowSubmitStateDynamically(showState, showErrors)

Sets whether the submit elements dynamically update
their state depending on the current values in the form.
The visibility of errors can be controlled via the
showErrors parameter.

Parameters:
{boolean} showState: true to have the elements update dynamically
{boolean} showErrors: true to show any validation errors that occur

setSubmitAsJSON(submitAsJSON)

Enables or disables submitting the form data in JSON format.
Setting the enctype attribute of the form to "application/json"
in Firefox will achieve the same result.

Parameters:
{boolean} submitAsJSON: true to submit the form data as JSON,
false to submit one of the standard types "multipart/form-data"
or "application/x-www-form-urlencoded" depending on the enctype
attribute on the form

setSubmitElements(submitElements)

Sets the list of ids and/or elements being used to submit the form.
By default the forms runtime will look for and use the first
input field of type submit found in the form being managed.

Parameters:
submitElements: {object | object[]} Single object or array of objects

setValidateAllOnSubmit(validate)

Sets whether all fields are validated when the form is submitted.

Parameters:
{boolean} validate: true to validate all fields on submission, false
to stop after the first validation failure

setValidateOnSubmit(validate)

Enables or disables validation when the form is submitted.

Parameters:
{boolean} validate: true to validate on submission, false
to avoid validation

updateSubmitElements()

Updates the state of all submit elements.

Classes

Class Alfresco.forms.Form