Form

Creates a HTML form with many additional options for handling its submission.

Tag Attributes

<ss:forms:form />

Method=""
The form submit method
Set to 'get' to submit form item values through the GET query string Set to 'post' to submit form item values through the POST http headers Set to 'ajax' to submit form item values through an AJAX xhttprequest POST

Action=""
The URL the form will submit to
If a form action is specified, post back events will not fire and the functionality of automatic handling of data may lost

EncType=""
The form content encoding type
Different encoding types are required for uploading different types of data. application/x-www-form-urlencoded Form data is encoded as name/value pairs. multipart/form-data Form data is encoded as a message with a separate part for each control on the page. text/plain Form data is encoded in plain text, without any control or formatting characters.

ReadOnly=""
Sets whether the form items can be edited or not

LeavePageWarning=""
If a user modifies the contents of a form and navigates away without
saving their changes, should a warning be displayed?

NoRefresh=""
If no refresh is set to true, the form wont repost when refreshed

DisableCSRF=""
Determines if CSRF should be disabled for the current form

ControlSSubmit=""
If ControlSSubmit is true, the form will submit when Ctrl+S is pressed on the keyboard

As=""
The name of the variable to be registered

OnSubmitRedirect=""
The URL to be redirected to upon successful form submission

OnSuccessToastMessage=""
The toast message to be displayed upon successful form submission

OnSuccessCloseDialog=""
If the form has submitted successfully, the parent dialog will close

OnSuccessRemoveGetVars=""
If the form is submitted and redirecting, remove these query string parameters

OnSubmitEmail=""
If set, an email will be sent with the contents of the form to the email addresses

OnSubmitEmailAttachmentsMaxSize=""
If set, the attachments of an email cannot exceed the specified maximum size in MB

OnSubmitEmailSubject=""
The e-mail subject when used in conjunction with OnSubmitEmail

OnSubmitAutoRespondPage=""
When submitted, this page will be sent to the currently logged in contact

OnSubmitAutoRespondSubject=""
Used in addition to OnSubmitAutoRespondPage, sets the subject

ContactMode=""
Options for interfacing with contacts
Valid values: register - Registers the contact and fails validation if the contact already exists store - Optionally registers the contact if they do not exist guest - Same as 'store' but creates a New Contact and does not log the current user in login - Logs in the contact (requires contact_email and contact_password fields) logout - Logs out the contact unsubscribe - Unsubscribes the contact

ContactGroupAdd=""
When the form is submitted, the contact is added to this group
You can specify multiple groups by using commas eg: contactgroupadd="/platinum/,/staff/"

ContactGroupRemove=""
When the form is submitted, the contact is removed from this group
You can specify multiple groups by using commas eg: contactgroupremove="/platinum/,/staff/"

ContactPrefill=""
If the current user is logged in, should the form be prefilled with their details

RecordSubmissions=""
Whether or not to record the submission

DataColumn=""
The data column of the parent form to store the id of the

SaveState=""
When set to true, the value of all child form items is persisted when the page is revisited

DataSource=""
Sets the data source for retreiving the entity

Component=""
Sets the data adapter
Allows the form to interface with data adapters

ComponentGet=""
Sets the data adapter get function
This function is invoked upon the Component class

ComponentSave=""
Sets the data adapter save function
This function is invoked upon the Component class

ComponentAutoSave=""
Sets whether or not to automatically save to the data adapter on form submit

ComponentKey=""
Sets the key for the data adapter

ComponentUpdateId=""
Returns the id of the record which was updated

Values=""
Returns an array of form item names => values

ValuesForComponent=""
Returns an array of form item datacolumns => values

ValueIgnore=""
Sets the ValueIgnore property
datacolumn - The field from the datasource will be ignored client - Any value supplied by the client will be ignored ajax - Any value supplied by the client throught ajax will be ignored empty - Any empty value will be ignored

IsPostBack=""
Returns whether or not the form has been sent back to the server
Regardless of whether form items failed to validate, or the item that caused the form to be sent.

IsSubmitted=""
Returns whether or not the form has been submitted successfully
If a form has been submitted by the client by clicking a button this method will return true. This method is handy if you wish to do custom form handling. This method will return false if form item failed to validate

IsValidationFailed=""
Returns true if a field on the form has failed to validate

Width=""
Sets the width of the element

Height=""
Sets the height of the element

Id=""
Sets id of the object - used for the html id attribute and referencing in the parser's
document object model

AttributeSet=""
Calls setAttribute() for each key value pair in $arrAttributes

AjaxModified=""
Sets whether or not this object is modified by ajax requests

AjaxEventParameter=""
Sets a parameter which can be passed to the ajax event
Be careful with security on this parameter as it is passed through javascript in the clients browser.

ChildNodes=""
Sets the children of this node in the DOM

InnerText=""
Adds a new TextNode child at the end of the children

Class Methods

The following methods can be invoked on instances of this class.

getNodeName()

getNodeDisplayType()

getParentForm()

Returns the parent form

getChildForms()

Returns any child forms

getRequiresId()

setDataSource(string pDataSource)

Sets the data source for retreiving the entity

getDataSource()

Returns the current data source

setComponent(string strComponent)

Sets the data adapter
Allows the form to interface with data adapters

getComponent()

Returns the data adapter class name

setComponentGet(string strComponentGet)

Sets the data adapter get function
This function is invoked upon the Component class

getComponentGet()

Returns the data adapter get function

setComponentSave(string strComponentSave)

Sets the data adapter save function
This function is invoked upon the Component class

getComponentSave()

Returns the data adapter save function

setComponentAutoSave(bool bComponentAutoSave)

Sets whether or not to automatically save to the data adapter on form submit

getComponentAutoSave()

Returns whether or not to automatically save to the data adapter on form submit

setComponentKey(string strComponentKey)

Sets the key for the data adapter

getComponentKey()

Returns the data adapter key

setComponentUpdateId(mixed iUpdateId)

getComponentUpdateId()

Returns the id of the record which was updated

addFormItem(mixed pItem)

Adds a form item to the current form

isFormItem(mixed strName)

Returns whether or not a form item with name $strName has been added to the form

removeFormItem(mixed strName)

Removes a form item

getFormItemPrimaryKey()

Returns the primary key form item
Pre: The form item must be added to the form

getFormItem(string strName)

Returns a form item with name $strName
If the form item does not exist, the method returns null

getFormItemByDataColumn(string strDataColumn)

Returns a form item with name $strName
If the form item does not exist, the method returns null

getFormItems()

Returns all form items attached to this form

getValues()

Returns an array of form item names => values

getValuesForComponent()

Returns an array of form item datacolumns => values

getValueFromDataSource(string strColumn)

Returns a value of a data column from a data source

getValueForFormItem(string strName)

Returns the value of a form item

getValueForFormItemIfExists(mixed strName, mixed returnValue)

Returns the value of a form item if it exists, otherwise $returnValue

setValueIgnore(string|array arrValueIgnore)

Sets the ValueIgnore property
datacolumn - The field from the datasource will be ignored client - Any value supplied by the client will be ignored ajax - Any value supplied by the client throught ajax will be ignored empty - Any empty value will be ignored

getValueIgnore()

Returns the ValueIgnore property

getHasPopulated()

Returns whether the form has populated items with datacolumns yet

getIsPopulateReady()

Returns whether or not the form is ready to populate

populate()

Populates all form items with values from the Component

setData(mixed arrData)

ajaxReset()

Resets the values of all form items during an ajax server event

csrfTokenGet()

Retrieves or generatesthe current CSRF token for the session

csrfTokenRender()

Returns the CSRF token HTML code for the current form

csrfTokenValidate()

Validates a CSRF token for the current form

isPostBack()

Returns whether or not the form has been sent back to the server
Regardless of whether form items failed to validate, or the item that caused the form to be sent.

isSubmitted()

Returns whether or not the form has been submitted successfully
If a form has been submitted by the client by clicking a button this method will return true. This method is handy if you wish to do custom form handling. This method will return false if form item failed to validate

isValidationFailed()

Returns true if a field on the form has failed to validate

validationExceptionPush(\Framework\Exceptions\Validation pException)

Pushing an exception onto the stack, making the submission invalid

validationExceptionGetAll()

Returns all validation exceptions for the form which aren't attached to a control

save()

Saves the form items to the data adapter

initialize()

onDOMReady()

Called when the entire document is initialized
This method invokes the event onDOMReadyServer

onPostBack()

onSubmit()

onSubmitSpamPrevention()

Performs spam detection and prevention

onSubmitContactMode()

Called on submit, when the form has the contactmode attribute
Performs functions to do with contacts

onSubmitContactGroup(mixed iContactId)

Called on submit, when the form has the contactgroup attribute
Adds a contact to a group on submit

onSubmitRecordSubmission()

Records correspondence for the form submission

onSubmitEmail(mixed iSubmissionId, mixed iSpamScore)

Called on submit, when the form has the OnSubmitEmail attribute
Sends an email to the specified address

onSubmitAutoRespond(mixed iContactId)

Called on submit, when the form has the OnSubmitAutoRespondPage attribute

onSubmitRedirect()

onSubmitToast()

When the form is successfully submitted, show toast messages

renderReturnForEmail()

Renders and returns the form for sending an its submission contents via en e-mail

renderTagOpen(mixed arrAttributes)

Renders the opening tag

renderTagClose()

Renders the closing tag

__sleep()

getTagNameHTML()

Returns the base tag name

getTagNameClosedInline()

Returns whether the tag is closed inline

setWidth(mixed strWidth)

Sets the width of the element

getWidth()

Returns the width of the element

setHeight(mixed strHeight)

Sets the height of the element

getHeight()

Returns the height of the element

getJSAttributes()

Returns a set of JavaScript attributes that differ from the default JS implementation
Default values on properties can be specified by @js_attribute and @js_default

getAttributesString(mixed arrOverrides, mixed bId, bool bSize)

Returns the attributes of the elment as a renderable properties string

generateId()

Generates an id for the node if one isnt already set

getRequiresContainerDiv()

Returns whether or not this control will be wrapped in a container span

RestoreControlFromState(string strId)

Restores a control from its element state

setId(string strId)

Sets id of the object - used for the html id attribute and referencing in the parser's
document object model

getId()

Returns the id of the object

__get(string strName)

Overload for returning an attribute

__set(mixed strName, string strValue)

Overload for setting an attribute

__isset(string strName)

Returns whether an attribute exists

__unset(string strName)

Removes an attribute

__destruct()

setAttribute(mixed strAttribute, string strValue, mixed bDecode)

Sets an attribute
Returns true when handled Returns false when set as standard a HTML attribute

setAttributes(array arrAttributes)

Calls setAttribute() for each key value pair in $arrAttributes

setAttributesHTML(array arrAttributes)

Sets generic HTML attributes not specified by attributes of this control

getAttributesHTML(array arrAttributes)

Returns the current attributes set that aren't defined attributes of this control

setAttributeHTML(mixed strAttribute, mixed strValue)

Sets a single attribute

getAttributeHTML(mixed strAttribute)

Returns a single attribute

setAttributeJSAdd(mixed strAttrib, mixed strValue)

Adds a javascript handler attribute
If a handlers already exist, the new handler added to the end

getAttribute(mixed strAttribute)

Returns the value of the given attribute

removeAttribute(string strAttrib)

Removes an attribute

getAttributes()

Returns the objects attributes as an associative array

requireAttribute(mixed strAttribute, mixed strValue)

setAttributesParsedInit(mixed arrAttributes)

getAttributesParsedInit()

setAttributesParsedRender(mixed arrAttributes)

getAttributesParsedRender()

mergeAttributes(mixed arr1, array arr2)

Merges two sets of attributes

getStyles()

setStyle(mixed strStyle, mixed strValue)

setStyles(mixed arrStyles)

setAjaxModified(bool bAjaxModified)

Sets whether or not this object is modified by ajax requests

getAjaxModified()

Returns whether or not this object is modified by ajax requests

stateGetSavableProperties()

Returns a list of properties which will be saved to session state

stateGetSavablePropertiesAllAttributes()

Returns a list of all attributes to save to session state

stateSave()

Serializes the state of the object to session

stateSaveAdditional(mixed strKey, string strValue)

Sets a key value pair for saving additional state data
This data is handled manually by each inheriting control

stateIsSetAdditional(string strKey)

Returns whether an additional state key has been set

stateGetAdditional(string strKey)

Returns the value of a key in the additional state set
Note: This function returns a reference

stateUnsetAdditional(string strKey)

Deletes additional saved data

stateSaveAdditionalArray(mixed strKey, mixed strKey2, mixed strValue)

Sets an inner array key value pair for saving additional state data

stateIsSetAdditionalArray(mixed strKey, string strKey2)

Returns whether an additional state key has been set

stateGetAdditionalArray(mixed strKey, string strKey2)

Returns an inner array key value pair for additional state data

stateGetPrevious()

Returns the state data for the current object

stateRenderJSGetContents()

stateRenderJS()

stateRestore(mixed arrAttributes)

Restores the saved state of this object from the users session

addEventHandler(mixed strEventName, mixed strCode)

Adds an event handler
If $strCode is an array, call_user_func_array will be called directly call_user_func_array($strFunc[0], $strFunc[1]);

removeEventHandler(mixed strEventName)

triggerEvent(string strEventName)

Triggers a server side event
Calls all event handlers set by addEventHandler

setEventHandlersAjax(array arrHandlers)

Sets the ajax event handlers

addEventHandlerAjax(mixed strEventName, mixed strAjaxEventId)

Adds an AJAX event handler

getEventHandlersAjax()

Sets the ajax event handlers

setAjaxEventParameter(string strParameter)

Sets a parameter which can be passed to the ajax event
Be careful with security on this parameter as it is passed through javascript in the clients browser.

getAjaxEventParameter()

Returns the current ajax event parameter

getIsAjax()

callDelegate(string strFunc)

Trigger an event by evaluating the script in $strFunc

onDOMReadySetParsedAttributes()

onDOMReadySetParsedAttributesAJAX()

render()

Renders the element

renderTagContents()

Renders the contents of the tag

renderAJAXTree(mixed bInside)

__sleepExport()

Magic function for a better var_export() of nodes

__wakeup()

Wake up

__clone()

Clone

__toString()

Renders the element to a string

getTrimContents()

Returns whether the control should trim its contents for optimisation purposes

setParentNode(\Framework\DOM\Nodes\NodeABC pNode)

Sets the elements parent node in the DOM

getParentNode()

Returns the elements parent node in the DOM

getAscendant(string strAscendantClass)

Returns the first ascendant node of a specific class

getDocument()

Returns the elements top most / document element

setChildNodesFromTemplate(array arrChildNodes)

Sets the child nodes from the template
This method may be overridden if the innerHTML from the original source acts as a template, rather than being the nodes themselves. For example, a data repeater uses the child nodes from the template to construct the child nodes dynamically.

setChildNodes(array arrChildNodes)

Sets the children of this node in the DOM

getChildNodes()

Returns the children of this node

insertBefore(mixed pNewNode, mixed pNode)

insertAfter(mixed pNewNode, mixed pNode)

appendChild(\Framework\DOM\Nodes\NodeABC pNode)

Adds new child at the end of the children

appendChildText(mixed strText)

Adds a new TextNode child at the end of the children

removeChild(\Framework\DOM\Nodes\NodeABC pNode)

Removes the specified node from the list of children

debugRenderChildren(mixed iDepth)

resetDOMStates()

Resets the indicators for dom states so that reinitialisation / rendering can occur

uiStateGetParentVars()

Returns an array containing the states of parent controls
such as DialogBox and TabList

__call(mixed strName, array arrArguments)

Magic function to trap calls to undefined functions and throw an exception rather than
a fatal error.

__callStatic(mixed strName, array arrArguments)

Magic function to trap static calls to undefined functions and throw an exception rather
than a fatal error.

classGetFolder()

Returns the folder where the class exists

__set_state(mixed arrValues)

classGetFolderResources()

Returns the folder where the class's resources exist

classGetSrcFile()

Returns the folder where the class exists

classGetSrcHash()

Returns the folder where the class exists

classGetReflection()

Returns the reflection data for the current class

classGetReflectionAnnotation(string strField)

Returns a specific class annotation for the current class