SwatObject
└─SwatUIObject
└─SwatWidget
└─SwatContainer
└─SwatDisplayableContainer
└─SwatForm
public class SwatForm
extends SwatDisplayableContainer
| Field Summary | |
|---|---|
| final mixed | |
| final mixed | |
| final mixed | |
| final mixed | |
| final mixed | |
| final mixed | |
| string | The action attribute of the HTML form tag. |
| boolean | Whether or not to automatically focus the a default SwatControl when this form loads. |
| SwatButton | A reference to the button that was clicked to submit the form, or null if the button is not set. |
| SwatControl | A reference to the default control to focus when the form loads. |
| static string | The default value to use for signature salt. |
| string | Encoding type of the form. |
| protected array | Hidden form fields. |
| protected string | The value to use when salting serialized data signatures. |
| Constructor Summary | |
|---|---|
SwatForm(string id) Creates a new form. |
|
| Method Summary | |
|---|---|
| void | addHiddenField(string name, mixed value) Adds a hidden form field. |
| void | addWithField(SwatWidget widget, string title) Adds a widget within a new SwatFormField. |
| static void | Clears the token value used to prevent cross-site request forgeries. |
| void | Clears all hidden fields. |
| void | display() Displays this form. |
| protected void | Displays hidden form fields. |
| protected array | Gets the array of CSS classes that are applied to this form. |
| array | Returns the super-global array with this form's data. |
| protected SwatHtmlTag | Gets the XHTML form tag used to display this form. |
| mixed | getHiddenField(string name) Gets the value of a hidden form field. |
| protected string | Gets inline JavaScript required for this form. |
| string | Gets the HTTP method this form uses to send data. |
| string | getSalt() Gets the salt value to use when salting signature data. |
| boolean | Whether or not this form is authenticated. |
| boolean | Whether or not this form was submitted on the previous page request. |
| protected void | notifyOfAdd(SwatWidget widget) Notifies this widget that a widget was added. |
| true | process() Processes this form. |
| protected void | Checks submitted form data for hidden fields. |
| protected string | serializeHiddenField(mixed value) Serializes a hidden field value into a string safe for including in form data. |
| static void | setAuthenticationToken(string token) Sets the token value used to prevent cross-site request forgeries. |
| void | setMethod(string method) Sets the HTTP method this form uses to send data. |
| void | setSalt(string salt) Sets the salt value to use when salting signature data. |
| protected mixed | unserializeHiddenField(string value) Unserializes a hidden field value that was serialized using SwatForm::serializeHiddenField(). |
| Methods inherited from Swat.SwatDisplayableContainer | |
|---|---|
| display, getCSSClassNames | |
| Methods inherited from Swat.SwatContainer | |
|---|---|
| add, addChild, copy, display, displayChildren, getChild, getChildren, getDescendantStates, getDescendants, getFirst, getFirstDescendant, getFocusableHtmlId, getHtmlHeadEntrySet, getMessages, hasMessage, init, notifyOfAdd, packEnd, packStart, printWidgetTree, process, remove, replace, sendAddNotifySignal, setDescendantStates | |
| Methods inherited from Swat.SwatWidget | |
|---|---|
| addCompositeWidget, addMessage, confirmCompositeWidgets, copy, createCompositeWidgets, display, displayHtmlHeadEntries, getCSSClassNames, getCompositeWidget, getCompositeWidgets, getFocusableHtmlId, getHtmlHeadEntrySet, getMessages, hasMessage, init, isDisplayed, isInitialized, isProcessed, isSensitive, printWidgetTree, process, replaceWithContainer | |
| Methods inherited from Swat.SwatUIObject | |
|---|---|
| addComment, addJavaScript, addStyleSheet, addTangoAttribution, copy, getCSSClassNames, getCSSClassString, getFirstAncestor, getHtmlHeadEntrySet, getInlineJavaScript, getUniqueId, isVisible | |
public final mixed AUTHENTICATION_TOKEN_FIELD = '_swat_form_authentication_token'
public final mixed HIDDEN_FIELD = '_swat_form_hidden_fields'
public final mixed METHOD_GET = 'get'
public final mixed METHOD_POST = 'post'
public final mixed PROCESS_FIELD = '_swat_form_process'
public final mixed SERIALIZED_PREFIX = '_swat_form_serialized_'
public string $action = '#'
The action attribute of the HTML form tag
public boolean $autofocus = false
Whether or not to automatically focus the a default SwatControl when this form loads
Autofocusing is good for applications or pages that are keyboard driven -- such as data entry forms -- as it immediatly places the focus on the form.
public SwatButton $button = null
A reference to the button that was clicked to submit the form, or null if the button is not set.
You usually do not want to explicitly set this in your code because other parts of Swat set this proprety automatically.
public SwatControl $default_focused_control = null
A reference to the default control to focus when the form loads
If this is not set then it defaults to the first SwatControl in the form.
public static string $default_salt = null
The default value to use for signature salt
If this value is not null, all newly instantiated forms will call the
SwatForm::setSalt() method with this value as the $salt
parameter.
public string $encoding_type = null
Encoding type of the form
Used for multipart forms for file uploads.
protected array $hidden_fields = array()
Hidden form fields
An array of the form: name => value where all the values are passed as hidden fields in this form.
protected string $salt = null
The value to use when salting serialized data signatures
public SwatForm(string id)
Creates a new form
id - a non-visible unique id for this widget.public void addHiddenField(string name, mixed value)
Adds a hidden form field
Adds a form field to this form that is not shown to the user. Hidden
form fields are outputted as type="hidden" input tags. Values are
serialized before being output so the value can be either a primitive
type or an object. Unserialization happens automatically when
SwatForm::getHiddenField() is used to retrieve the value. For
non-array and non-object types, the value is also stored as an
unserialized value that can be retrieved without using
SwatForm::getHiddenField().
name - the name of the field.value - the value of the field, either a string or an array.public void addWithField(SwatWidget widget, string title)
Adds a widget within a new SwatFormField
This is a convenience method that does the following: - creates a new SwatFormField, - adds the widget as a child of the form field, - and then adds the SwatFormField to this form.
widget - a reference to a widget to add.title - the visible title of the form field.public static void clearAuthenticationToken()
Clears the token value used to prevent cross-site request forgeries
After this method is called, no cross-site request forgery detection can be performed, and all forms will be considered authenticated. This is acceptable if a user's session is ending and the threat of cross-site request forgeries is gone.
public void clearHiddenFields()
Clears all hidden fields
public void display()
Displays this form
Outputs the HTML form tag and calls the display() method on each child widget of this form. Then, after all the child widgets are displayed, displays all hidden fields.
This method also adds a hidden field called 'process' that is given the unique identifier of this form as a value.
protected void displayHiddenFields()
Displays hidden form fields
Displays hiden form fields as XHTML elements. This method automatically handles array type values so they will be returned correctly as arrays.
This methods also generates an array of hidden field names and passes them as hidden fields.
If an authentication token is set on this form to prevent cross-site request forgeries, the token is displayed in a hidden field.
protected array getCSSClassNames()
Gets the array of CSS classes that are applied to this form
public array getFormData()
Returns the super-global array with this form's data
Returns a reference to the super-global array containing this form's data. The array is chosen based on this form's method.
protected SwatHtmlTag getFormTag()
Gets the XHTML form tag used to display this form
public mixed getHiddenField(string name)
Gets the value of a hidden form field
name - the name of the field whose value to get.protected string getInlineJavaScript()
Gets inline JavaScript required for this form
Right now, this JavaScript focuses the first SwatControl in the form.
public string getMethod()
Gets the HTTP method this form uses to send data
public string getSalt()
Gets the salt value to use when salting signature data
SwatInputControl widgets may want ot use this value for salting
their own data. This can be done using:
<?php
$salt = $this->getForm()->getSalt();
?>
public boolean isAuthenticated()
Whether or not this form is authenticated
This can be used to catch cross-site request forgeries if the
SwatForm::setAuthenticationToken() method was previously called.
If form authentication is used, processing should only be performed on authenticated forms. An unauthenticated form may be a malicious request.
public boolean isSubmitted()
Whether or not this form was submitted on the previous page request
This method may becalled before or after the SwatForm::process() method. and is thus sometimes more useful than SwatForm::isProcessed() which only returns a meaningful value after SwatForm::process() is called.
protected void notifyOfAdd(SwatWidget widget)
Notifies this widget that a widget was added
If any of the widgets in the added subtree are file entry widgets then set this form's encoding accordingly.
widget - the widget that has been added.public true process()
Processes this form
If this form has been submitted then calls the process() method on each child widget. Then processes hidden form fields.
This form is only marked as processed if it was submitted by the user.
protected void processHiddenFields()
Checks submitted form data for hidden fields
Checks submitted form data for hidden fields. If hidden fields are found, properly re-adds them to this form.
protected string serializeHiddenField(mixed value)
Serializes a hidden field value into a string safe for including in form data
value - the hidden field value to serialize.public static void setAuthenticationToken(string token)
Sets the token value used to prevent cross-site request forgeries
After the authentication token is set, when any form is processed, the the submitted form data must contain this token.
For the safest results, this token should be taken from an active session. For usability reasons, the same token should be used for the same user over multiple requests. The token should be unique to a user's session and should be difficult to guess.
token - the value used to prevent cross-site request forgeries.public void setMethod(string method)
Sets the HTTP method this form uses to send data
method - a method constant. Must be one of SwatForm::METHOD_* otherwise an error is thrown.public void setSalt(string salt)
Sets the salt value to use when salting signature data
salt - the value to use when salting signature data.protected mixed unserializeHiddenField(string value)
Unserializes a hidden field value that was serialized using
SwatForm::serializeHiddenField()
value - the hidden field value to unserialize.
A form widget which can contain other widgets
SwatForms are very useful for processing widgets. For most widgets, if they are not inside a SwatForm they will not be able to be processed properly.
With Swat's default style, SwatForm widgets have no visible margins, padding or borders.