Class Form

Base class for all forms. The form class is an extensible base for all forms on a sapphire application. It can be used either by extending it, and creating processor methods on the subclass, or by creating instances of form whose actions are handled by the parent controller.

In either case, if you want to get a form to do anything, it must be inextricably tied to a controller. The constructor is passed a controller and a method on that controller. This method should return the form object, and it shouldn't require any arguments. Parameters, if necessary, can be passed using the URL or get variables. These restrictions are in place so that we can recreate the form object upon form submission, without the use of a session, which would be too resource-intensive.

You will need to create at least one method for processing the submission (through FormAction). This method will be passed two parameters: the raw request data, and the form object. Usually you want to save data into a DataObject by using Form::saveInto(). If you want to process the submitted data in any way, please use Form::getData() rather than the raw request data.

Validation

Each form needs some form of Validator to trigger the FormField->validate() methods for each field. You can't disable validator for security reasons, because crucial behaviour like extension checks for file uploads depend on it. The default validator is an instance of RequiredFields. If you want to enforce serverside-validation to be ignored for a specific FormField, you need to subclass it.

URL Handling

The form class extends RequestHandler, which means it can be accessed directly through a URL. This can be handy for refreshing a form by ajax, or even just displaying a single form field. You can find out the base URL for your form by looking at the <form action="..."> value. For example, the edit form in the CMS would be located at "admin/EditForm". This URL will render the form without its surrounding template when called through GET instead of POST.

By appending to this URL, you can render invidual form elements through the FormField->FieldHolder() method. For example, the "URLSegment" field in a standard CMS form would be accessible through "admin/EditForm/field/URLSegment/FieldHolder".

Object

ViewableData implements IteratorAggregate

RequestHandler

Form

Direct known subclasses

ChangePasswordForm, CMSActionOptionsForm, Order_CancelForm, PageCommentInterface_Form, RecipientImportField_UploadForm, SearchForm, ShowPoll, Unsubscribe_MailingListForm, ComplexTableField_Popup, DataObjectManager_Popup, DocumentSearchForm, GroupImportForm, LoginForm, MediawebForm, Member_ProfileForm, MemberImportForm

Indirect known subclasses

AdvancedSearchForm, FileDataObjectManager_Popup, ImageDataObjectManager_Popup, MediawebPage_Popup, MemberLoginForm, MemberTableField_Popup, PhotoAlbumManager_Popup, ScaffoldingComplexTableField_Popup

Package: forms\core
Located at sapphire/forms/Form.php

Methods summary

`public`	# `__construct( Controller $controller, String $name, FieldSet $fields, FieldSet $actions, Validator $validator = null )` Create a new form, with the given fields an action buttons. Create a new form, with the given fields an action buttons. Parameters `$controller` Controller $controller The parent controller, necessary to create the appropriate form action tag. `$name` String $name The method on the controller that will return this form object. `$fields` FieldSet $fields All of the fields in the form - a `FieldSet` of `FormField` objects. `$actions` FieldSet $actions All of the action buttons in the form - a `FieldSet` of `FormAction` objects `$validator` Validator $validator Override the default validator instance (Default: `RequiredFields`) Overrides `RequestHandler::__construct`
`public`	# `setupFormErrors( )` Set up current form errors in session to the current form if appropriate. Set up current form errors in session to the current form if appropriate.
`public`	# `httpSubmission( mixed $request )` Handle a form submission. GET and POST requests behave identically. Populates the form with `Form::loadDataFrom()`, calls `Form::validate()`, and only triggers the requested form action/method if the form is valid. Handle a form submission. GET and POST requests behave identically. Populates the form with `Form::loadDataFrom()`, calls `Form::validate()`, and only triggers the requested form action/method if the form is valid.
`public FormField`	# `handleField( SS_HTTPRequest $request )` Handle a field request. Uses Form->dataFieldByName() to find a matching field, and falls back to FieldSet->fieldByName() to look for tabs instead. This means that if you have a tab and a formfield with the same name, this method gives priority to the formfield. Handle a field request. Uses Form->dataFieldByName() to find a matching field, and falls back to FieldSet->fieldByName() to look for tabs instead. This means that if you have a tab and a formfield with the same name, this method gives priority to the formfield. Parameters `$request` SS_HTTPRequest $request Returns `FormField` FormField
`public`	# `makeReadonly( )` Convert this form into a readonly form Convert this form into a readonly form
`public`	# `setRedirectToFormOnValidationError( boolean $bool )` Set whether the user should be redirected back down to the form on the page upon validation errors in the form or if they just need to redirect back to the page Set whether the user should be redirected back down to the form on the page upon validation errors in the form or if they just need to redirect back to the page Parameters `$bool` bool Redirect to the form
`public boolean`	# `getRedirectToFormOnValidationError( )` Get whether the user should be redirected back down to the form on the page upon validation errors Get whether the user should be redirected back down to the form on the page upon validation errors Returns `boolean` bool
`public`	# `addErrorMessage( mixed $fieldName, mixed $message, mixed $messageType )` Add an error message to a field on this form. It will be saved into the session and used the next time this form is displayed. Add an error message to a field on this form. It will be saved into the session and used the next time this form is displayed.
`public`	# `transform( FormTransformation $trans )`
`public Validator`	# `getValidator( )` Get the `Validator` attached to this form. Get the `Validator` attached to this form. Returns `Validator` Validator
`public`	# `setValidator( Validator $validator )` Set the `Validator` on this form. Set the `Validator` on this form.
`public`	# `unsetValidator( )` Remove the `Validator` from this from. Remove the `Validator` from this from.
`public`	# `transformTo( FormTransformation $format )` Convert this form to another format. Convert this form to another format.
`public FieldSet`	# `getExtraFields( )` Generate extra special fields - namely the SecurityID field Generate extra special fields - namely the SecurityID field Returns `FieldSet` FieldSet
`public FieldSet`	# `Fields( )` Return the form's fields - used by the templates Return the form's fields - used by the templates Returns `FieldSet` The form fields
`public FieldSet`	# `HiddenFields( )` Return all <input type="hidden"> fields in a form - including fields nested in CompositeFields. Useful when doing custom field layouts. Return all <input type="hidden"> fields in a form - including fields nested in CompositeFields. Useful when doing custom field layouts. Returns `FieldSet` FieldSet
`public`	# `setFields( FieldSet $fields )` Setter for the form fields. Setter for the form fields. Parameters `$fields` FieldSet $fields
`public FormField`	# `dataFieldByName( mixed $name )` Get a named field from this form's fields. It will traverse into composite fields for you, to find the field you want. It will only return a data field. Get a named field from this form's fields. It will traverse into composite fields for you, to find the field you want. It will only return a data field. Returns `FormField` FormField
`public FieldSet`	# `Actions( )` Return the form's action buttons - used by the templates Return the form's action buttons - used by the templates Returns `FieldSet` The action list
`public`	# `setActions( FieldSet $actions )` Setter for the form actions. Setter for the form actions. Parameters `$actions` FieldSet $actions
`public`	# `unsetAllActions( )` Unset all form actions Unset all form actions
`public`	# `unsetActionByName( string $name )` Unset the form's action button by its name. Unset the form's action button by its name. Parameters `$name` string $name
`public`	# `unsetDataFieldByName( mixed $fieldName )` Unset the form's dataField by its name Unset the form's dataField by its name
`public`	# `unsetFieldFromTab( mixed $tabName, mixed $fieldName )` Remove a field from the given tab. Remove a field from the given tab.
`public string`	# `FormAttributes( )` Return the attributes of the form tag - used by the templates. Return the attributes of the form tag - used by the templates. Returns `string` The attribute string
`public`	# `setTarget( Form::$target $target )` Set the target of this form to any value - useful for opening the form contents in a new window or refreshing another frame Set the target of this form to any value - useful for opening the form contents in a new window or refreshing another frame Parameters `$target` target The value of the target
`public`	# `setLegend( mixed $legend )` Set the legend value to be inserted into the <legend> element in the Form.ss template. Set the legend value to be inserted into the <legend> element in the Form.ss template.
`public`	# `setTemplate( string $template )` Set the SS template that this form should use to render with. The default is "Form". Set the SS template that this form should use to render with. The default is "Form". Parameters `$template` string $template The name of the template (without the .ss extension)
`public string`	# `getTemplate( )` Return the template to render this form with. If the template isn't set, then default to the form class name e.g "Form". Return the template to render this form with. If the template isn't set, then default to the form class name e.g "Form". Returns `string` string
`public string`	# `FormEncType( )` Returns the encoding type of the form. This will be either "multipart/form-data"" if there are any `FileField` instances, otherwise "application/x-www-form-urlencoded" Returns the encoding type of the form. This will be either "multipart/form-data"" if there are any `FileField` instances, otherwise "application/x-www-form-urlencoded" Returns `string` The encoding mime type
`public string`	# `FormHttpMethod( )` Returns the real HTTP method for the form: GET, POST, PUT, DELETE or HEAD. As most browsers only support GET and POST in form submissions, all other HTTP methods are added as a hidden field "_method" that gets evaluated in `Director::direct()`. See `Form::FormMethod()` to get a HTTP method for safe insertion into a <form> tag. Returns the real HTTP method for the form: GET, POST, PUT, DELETE or HEAD. As most browsers only support GET and POST in form submissions, all other HTTP methods are added as a hidden field "_method" that gets evaluated in `Director::direct()`. See `Form::FormMethod()` to get a HTTP method for safe insertion into a <form> tag. Returns `string` HTTP method
`public string`	# `FormMethod( )` Returns the form method to be used in the <form> tag. See `Form::FormHttpMethod()` to get the "real" method. Returns the form method to be used in the <form> tag. See `Form::FormHttpMethod()` to get the "real" method. Returns `string` Form tag compatbile HTTP method: 'get' or 'post'
`public`	# `setFormMethod( mixed $method )` Set the form method: GET, POST, PUT, DELETE. Set the form method: GET, POST, PUT, DELETE. Parameters `$method` $method string
`public string`	# `FormAction( )` Return the form's action attribute. This is build by adding an executeForm get variable to the parent controller's Link() value Return the form's action attribute. This is build by adding an executeForm get variable to the parent controller's Link() value Returns `string` string
`public`	# `setFormAction( mixed $path )` Set the form action attribute to a custom URL. Set the form action attribute to a custom URL. Note: For "normal" forms, you shouldn't need to use this method. It is recommended only for situations where you have two relatively distinct parts of the system trying to communicate via a form post.
`public`	# `FormName( )` Returns the name of the form Returns the name of the form
`public`	# `setHTMLID( mixed $id )` Set the HTML ID attribute of the form Set the HTML ID attribute of the form
`public`	# `Controller( )` Returns this form's controller Returns this form's controller
`public string`	# `Name( )` Returns `string` string
`public`	# `FieldMap( )` Returns an object where there is a method with the same name as each data field on the form. That method will return the field itself. It means that you can execute $firstNameField = $form->FieldMap()->FirstName(), which can be handy Returns an object where there is a method with the same name as each data field on the form. That method will return the field itself. It means that you can execute $firstNameField = $form->FieldMap()->FirstName(), which can be handy
`public string`	# `Message( )` The next functions store and modify the forms message attributes. messages are stored in session under $_SESSION[formname][message]; The next functions store and modify the forms message attributes. messages are stored in session under $_SESSION[formname][message]; Returns `string` string
`public string`	# `MessageType( )` Returns `string` string
`protected`	# `getMessageFromSession( )`
`public`	# `setMessage( Form::$message $message, type $type )` Set a status message for the form. Set a status message for the form. Parameters `$message` message the text of the message `$type` type Should be set to good, bad, or warning.
`public`	# `sessionMessage( Form::$message $message, type $type )` Set a message to the session, for display next time this form is shown. Set a message to the session, for display next time this form is shown. Parameters `$message` message the text of the message `$type` type Should be set to good, bad, or warning.
`public static`	# `messageForForm( mixed $formName, mixed $message, mixed $type )`
`public`	# `clearMessage( )`
`public`	# `resetValidation( )`
`public DataObject`	# `getRecord( )` Returns the DataObject that has given this form its data through `Form::loadDataFrom()`. Returns the DataObject that has given this form its data through `Form::loadDataFrom()`. Returns `DataObject` DataObject
`public string`	# `getLegend( )` Get the legend value to be inserted into the <legend> element in Form.ss Get the legend value to be inserted into the <legend> element in Form.ss Returns `string` string
`public`	# `validate( )` Processing that occurs before a form is executed. This includes form validation, if it fails, we redirect back to the form with appropriate error messages. Triggered through `Form::httpSubmission()` which is triggered Processing that occurs before a form is executed. This includes form validation, if it fails, we redirect back to the form with appropriate error messages. Triggered through `Form::httpSubmission()` which is triggered
`public`	# `loadDataFrom( array\|DataObject $data, boolean $clearMissingFields = false, mixed $fieldList = null )` Load data from the given DataObject or array. It will call $object->MyField to get the value of MyField. If you passed an array, it will call $object[MyField]. Doesn't save into dataless FormFields (`DatalessField`), as determined by FieldSet->dataFields(). Load data from the given DataObject or array. It will call $object->MyField to get the value of MyField. If you passed an array, it will call $object[MyField]. Doesn't save into dataless FormFields (`DatalessField`), as determined by FieldSet->dataFields(). By default, if a field isn't set (as determined by isset()), its value will not be saved to the field, retaining potential existing values. Passed data should not be escaped, and is saved to the FormField instances unescaped. Escaping happens automatically on saving the data through `Form::saveInto()`. Parameters `$data` array\|DataObject $data `$clearMissingFields` boolean $clearMissingFields By default, fields which don't match a property or array-key of the passed $data argument are "left alone", meaning they retain any previous values (if present). If this flag is set to true, those fields are overwritten with null regardless if they have a match in $data. `$fieldList` $fieldList An optional list of fields to process. This can be useful when you have a form that has some fields that save to one object, and some that save to another. Uses `FieldSet::dataFields()` `FormField::setValue()`
`public`	# `saveInto( DataObjectInterface $dataObject, mixed $fieldList = null )` Save the contents of this form into the given data object. It will make use of setCastedField() to do this. Save the contents of this form into the given data object. It will make use of setCastedField() to do this. Parameters `$dataObject` $dataObject The object to save data into `$fieldList` $fieldList An optional list of fields to process. This can be useful when you have a form that has some fields that save to one object, and some that save to another.
`public array`	# `getData( )` Get the submitted data from this form through FieldSet->dataFields(), which filters out any form-specific data like form-actions. Calls FormField->dataValue() on each field, which returns a value suitable for insertion into a DataObject property. Get the submitted data from this form through FieldSet->dataFields(), which filters out any form-specific data like form-actions. Calls FormField->dataValue() on each field, which returns a value suitable for insertion into a DataObject property. Returns `array` array
`public`	# `resetField( string $fieldName, mixed $fieldValue = null )` Resets a specific field to its passed default value. Does NOT clear out all submitted data in the form. Resets a specific field to its passed default value. Does NOT clear out all submitted data in the form. Parameters `$fieldName` string $fieldName `$fieldValue` mixed $fieldValue
`public`	# `callfieldmethod( fieldName $data )` Call the given method on the given field. This is used by Ajax-savvy form fields. By putting '&action=callfieldmethod' to the end of the form action, they can access server-side data. Call the given method on the given field. This is used by Ajax-savvy form fields. By putting '&action=callfieldmethod' to the end of the form action, they can access server-side data. Parameters `$data` fieldName The name of the field. Can be overridden by $_REQUEST[fieldName]
`public`	# `forTemplate( )` Return a rendered version of this form. Return a rendered version of this form. This is returned when you access a form as $FormObject rather than <% control FormObject %>
`public`	# `forAjaxTemplate( )` Return a rendered version of this form, suitable for ajax post-back. It triggers slightly different behaviour, such as disabling the rewriting of # links Return a rendered version of this form, suitable for ajax post-back. It triggers slightly different behaviour, such as disabling the rewriting of # links
`public`	# `formHtmlContent( )` Returns an HTML rendition of this form, without the <form> tag itself. Attaches 3 extra hidden files, _form_action, _form_name, _form_method, and _form_enctype. These are the attributes of the form. These fields can be used to send the form to Ajax. Returns an HTML rendition of this form, without the <form> tag itself. Attaches 3 extra hidden files, _form_action, _form_name, _form_method, and _form_enctype. These are the attributes of the form. These fields can be used to send the form to Ajax.
`public`	# `renderWithoutActionButton( mixed $template )` Render this form using the given template, and return the result as a string You can pass either an SSViewer or a template name Render this form using the given template, and return the result as a string You can pass either an SSViewer or a template name
`public`	# `setButtonClicked( funcName $funcName )` Sets the button that was clicked. This should only be called by the Controller. Sets the button that was clicked. This should only be called by the Controller. Parameters `$funcName` funcName The name of the action method that will be called.
`public`	# `buttonClicked( )`
`public`	# `defaultAction( )` Return the default button that should be clicked when another one isn't available Return the default button that should be clicked when another one isn't available
`public`	# `disableDefaultAction( )` Disable the default button. Ordinarily, when a form is processed and no action_XXX button is available, then the first button in the actions list will be pressed. However, if this is "delete", for example, this isn't such a good idea. Disable the default button. Ordinarily, when a form is processed and no action_XXX button is available, then the first button in the actions list will be pressed. However, if this is "delete", for example, this isn't such a good idea.
`public`	# `disableSecurityToken( )` Disable the requirement of a SecurityID in the Form. This security protects against CSRF attacks, but you should disable this if you don't want to tie a form to a session - eg a search form. Disable the requirement of a SecurityID in the Form. This security protects against CSRF attacks, but you should disable this if you don't want to tie a form to a session - eg a search form.
`public static`	# `disable_all_security_tokens( )` Disable security tokens for every form on this site. Disable security tokens for every form on this site.
`public boolean`	# `securityTokenEnabled( )` Returns true if security is enabled - that is if the SecurityID should be included and checked on this form. Returns true if security is enabled - that is if the SecurityID should be included and checked on this form. Returns `boolean` bool
`public static string`	# `single_field_required( )` Returns the name of a field, if that's the only field that the current controller is interested in. It checks for a call to the callfieldmethod action. This is useful for optimising your forms Returns the name of a field, if that's the only field that the current controller is interested in. It checks for a call to the callfieldmethod action. This is useful for optimising your forms Returns `string` string
`public static`	# `current_action( )` Return the current form action being called, if available. This is useful for optimising your forms Return the current form action being called, if available. This is useful for optimising your forms
`public static`	# `set_current_action( mixed $action )` Set the current form action. Should only be called by Controller. Set the current form action. Should only be called by Controller.
`public String`	# `extraClass( )` Compiles all CSS-classes. Compiles all CSS-classes. Returns `String` CSS-classnames, separated by a space
`public`	# `addExtraClass( mixed $class )` Add a CSS-class to the form-container. Add a CSS-class to the form-container. Parameters `$class` $class String
`public`	# `removeExtraClass( mixed $class )` Remove a CSS-class from the form-container. Remove a CSS-class from the form-container. Parameters `$class` $class String
`public`	# `debug( )`
`public SS_HTTPResponse`	# `testSubmission( mixed $action, mixed $data )` Test a submission of this form. Test a submission of this form. Returns `SS_HTTPResponse` the response object that the handling controller produces. You can interrogate this in your unit test.
`public SS_HTTPResponse`	# `testAjaxSubmission( mixed $action, mixed $data )` Test an ajax submission of this form. Test an ajax submission of this form. Returns `SS_HTTPResponse` the response object that the handling controller produces. You can interrogate this in your unit test.

Magic methods summary

Properties summary

`public boolean`	`$IncludeFormTag`	# $includeFormTag Accessed by Form.ss; modified by `Form::formHtmlContent()`. A performance enhancement over the generate-the-form-tag-and-then-remove-it code that was there previously $includeFormTag Accessed by Form.ss; modified by `Form::formHtmlContent()`. A performance enhancement over the generate-the-form-tag-and-then-remove-it code that was there previously
`protected mixed`	`$fields`	#
`protected mixed`	`$actions`	#
`protected mixed`	`$controller`	#
`protected mixed`	`$name`	#
`protected mixed`	`$validator`	#
`protected string`	`$formMethod`	#
`protected static mixed`	`$current_action`	#
`protected Dataobject`	`$record`	# $record Populated by `Form::loadDataFrom()`. $record Populated by `Form::loadDataFrom()`.
`protected boolean`	`$hasDefaultAction`	# Keeps track of whether this form has a default action or not. Set to false by $this->disableDefaultAction(); Keeps track of whether this form has a default action or not. Set to false by $this->disableDefaultAction();
`protected string`	`$target`	# Target attribute of form-tag. Useful to open a new window upon form submission. Target attribute of form-tag. Useful to open a new window upon form submission.
`protected string`	`$legend`	# Legend value, to be inserted into the <legend> element before the <fieldset> in Form.ss template. Legend value, to be inserted into the <legend> element before the <fieldset> in Form.ss template.
`protected string`	`$template`	# The SS template to render this form HTML into. Default is "Form", but this can be changed to another template for customisation. The SS template to render this form HTML into. Default is "Form", but this can be changed to another template for customisation. See `Form::setTemplate()`
`protected mixed`	`$buttonClickedFunc`	#
`protected mixed`	`$message`	#
`protected mixed`	`$messageType`	#
`protected boolean`	`$redirectToFormOnValidationError`	# Should we redirect the user back down to the the form on validation errors rather then just the page Should we redirect the user back down to the the form on validation errors rather then just the page
`protected boolean`	`$security`	#
`public boolean`	`$jsValidationIncluded`	# HACK This is a temporary hack to allow multiple calls to includeJavascriptValidation on the validator (if one is present). HACK This is a temporary hack to allow multiple calls to includeJavascriptValidation on the validator (if one is present).
`protected array`	`$extraClasses`	# array Extra CSS-classes for the formfield-container array Extra CSS-classes for the formfield-container
`public static array`	`$url_handlers`	# The default URL handling rules. This specifies that the next component of the URL corresponds to a method to be called on this RequestHandlingData object. The default URL handling rules. This specifies that the next component of the URL corresponds to a method to be called on this RequestHandlingData object. The keys of this array are parse rules. See `SS_HTTPRequest::match()` for a description of the rules available. The values of the array are the method to be called if the rule matches. If this value starts with a '$', then the named parameter of the parsed URL wil be used to determine the method name.

Properties inherited from RequestHandler

$allowed_actions, $brokenOnConstruct, $request

Properties inherited from ViewableData

$casting, $customisedObject, $default_cast, $failover, $iteratorPos, $iteratorTotalItems

Properties inherited from Object

$class, $extension_instances, $extensions

Packages

Classes

Class Form

Validation

URL Handling

Direct known subclasses

Indirect known subclasses

Methods summary

Parameters

Overrides

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Returns

Parameters

Returns

Returns

Parameters

Parameters

Returns

Parameters

Parameters

Returns

Returns

Returns

Returns

Parameters

Returns

Returns

Returns

Returns

Parameters

Parameters

Returns

Returns

Parameters

Uses

Parameters

Returns

Parameters

Parameters

Parameters

Returns

Returns

Returns

Parameters

Parameters

Returns

Returns

Methods inherited from RequestHandler

Methods inherited from ViewableData

Methods inherited from Object

Magic methods summary

Properties summary

See

Properties inherited from RequestHandler

Properties inherited from ViewableData

Properties inherited from Object