FormManager Class
Required Markup Structure
Each element (or tighly coupled set of elements) must be contained by
an element that has the CSS class formmgr-row. Within each
row, validation messages are displayed inside the container with CSS
class formmgr-message-text.
When a message is displayed inside a row, the CSS class
formmgr-has{type} is placed on the row container and the
containing fieldset (if any), where {type} is the message
type passed to displayMessage().
Initializing the Form
Default values can be either encoded in the markup or passed to the
FormManager constructor via config.default_value_map. (The
former method is obviously better for progressive enhancement.) The
values passed to the constructor override the values encoded in the
markup.
prepareForm() must be called before the form is
displayed. To initialize focus to the first element in a form, call
initFocus(). If the form is in an overlay, you can delay
these calls until just before showing the overlay.
The default values passed to the constructor are inserted by
populateForm(). (This is automatically called by
prepareForm().)
Hidden fields are ignored. If you want FormManager to process a
value that is invisible to the user, use a normal input with
display:none;.
Displaying Messages
To display a message for a single form row, call
displayMessage(). To display a message for the form in
general, call displayFormMessage(). These functions can be
used for initializing the error display when the page loads, for
displaying the results of pre-validation, and for displaying the results
of submitting a form via XHR.
Specifying Validations
The following classes can be applied to a form element for pre-validation:
yiv-required- Value must not be empty.
yiv-length:[x,y]- String must be at least x characters and at most y characters. At least one of x and y must be specified.
yiv-integer:[x,y]- The integer value must be at least x and at most y. x and y are both optional.
yiv-decimal:[x,y]- The decimal value must be at least x and at most y. Exponents are not allowed. x and y are both optional.
If we ever need to allow exponents, we can use yiv-float.
The following functions allow additional pre-validation to be attached to individual form elements:
setRegex()- Sets the regular expression that must match in order for the value to be acceptable.
setFunction()- Sets the function that must return true in order for the value to be acceptable. The function is called in the scope of the Form object with the arguments: the form and the element.
setErrorMessages() specifies the error message to be
displayed when a pre-validation check fails.
Functions are expected to call displayMessage()
directly.
More complex pre-validations can be added by overriding
postValidateForm(), described below.
Validation normally strips leading and trailing whitespace from every
value. If you have a special case where this should not be done, add
the CSS class yiv-no-trim to the input field.
Derived classes may also override the following functions:
prePrepareForm(arguments passed to prepareForm)- Called before filling in default values for the form elements. Return false to cancel dialog.
postPrepareForm(arguments passed to prepareForm)- Called after filling in default values for the form elements.
postValidateForm(form)- Called after performing the basic pre-validations. Returns true if the form contents are acceptable. Reports error if there is a problem.
Constructor
FormManager
-
form_name -
config
Parameters:
-
form_nameStringThe name attribute of the HTML form.
-
configObjectConfiguration.
status_nodeis an optional element in which to display overall status.default_value_mapis an optional mapping of form element names to default values. Default values encoded in the markup will be merged into this map, but values passed to the constructor will take precedence.
Item Index
Methods
- addErrorMessage
- cleanValues static
- clearForm
- clearMessage static
- clearMessages
- disableForm
- displayFormMessage
- displayMessage
- displayMessage static
- enableForm
- getChanges
- getElementStatus static
- getForm
- getRowStatus
- getStatusPrecedence static
- hasErrors
- hasFileInputs
- hasMessages
- initFocus
- isChanged
- isFormEnabled
- notifyErrors
- populateForm
- postPopulateForm
- postPrepareForm
- postValidateForm
- prepareForm
- prePrepareForm
- registerButton
- saveCurrentValuesAsDefault
- setDefaultValue
- setDefaultValues
- setErrorMessages
- setFormEnabled
- setFunction
- setRegex
- setStatusNode
- statusTakesPrecedence static
- validateForm
- validateFromCSSData static
Properties
Methods
addErrorMessage
-
id -
error_type -
msg
Set one particular error message for a form element.
Parameters:
-
idString | ObjectThe selector for the element or the element itself
-
error_typeStringThe error message type. Refer to setErrorMessages() for details.
-
msgStringThe error message
cleanValues
-
e
Trim leading and trailing whitespace from the specified fields, except when a field has the CSS class yiv-no-trim.
Parameters:
-
eArrayThe fields to clean.
Returns:
true if there are any file inputs.
clearForm
()
Reset all values in the form to the defaults specified in the markup.
clearMessage
-
e
Exposed for use by Y.QueryBuilder
Clear the message for the given field.
Parameters:
-
eElement | Nodethe field
clearMessages
()
Clear all messages in status_node and the form rows.
disableForm
()
Disable all the registered buttons.
displayFormMessage
-
msg -
error -
scroll
Display a message in status_node.
Parameters:
-
msgStringThe message
-
errorBooleantrueif the message is an error -
scrollBooleantrueifstatus_nodeshould be scrolled into view
displayMessage
-
e -
msg -
type -
[scroll]
Display a message for the form row containing the specified element. The message will only be displayed if no message with a higher precedence is already visible. (see Y.FormManager.status_order)
Parameters:
-
eString | ObjectThe selector for the element or the element itself
-
msgStringThe message
-
typeStringThe message type (see Y.FormManager.status_order)
-
[scroll]Boolean optionaltrueif the form row should be scrolled into view
Returns:
true if the message was displayed, false if a higher precedence message was already there
displayMessage
-
e -
msg -
type -
[had_messages] -
[scroll]
Exposed for use by Y.QueryBuilder
Display a message for the form row containing the specified element. The message will only be displayed if no message with a higher precedence is already visible. (see Y.FormManager.status_order)
Parameters:
-
eString | ObjectThe selector for the element or the element itself
-
msgStringThe message
-
typeStringThe message type (see Y.FormManager.status_order)
-
[had_messages]Boolean optionaltrueif the form already has messages displayed -
[scroll]Boolean optionaltrueif the form row should be scrolled into view
Returns:
true if the message was displayed, false if a higher precedence message was already there
enableForm
()
Enable all the registered buttons.
getChanges
()
Object
Return the modified values.
Returns:
map of form element names to new values
getElementStatus
-
e
Get the status of the given fieldset or form row.
Parameters:
-
eString | ObjectThe descriptor or DOM element.
Returns:
The status (String) or false.
getRowStatus
-
e
Get the message type displayed for the row containing the specified element.
Parameters:
-
eString | ObjectThe selector for the element or the element itself
Returns:
The status (String) or false.
getStatusPrecedence
-
status
Get the precedence of the given status name.
Parameters:
-
statusStringThe name of the status value.
Returns:
The position in the status_order array.
hasErrors
()
Boolean
Returns:
true if there are any error messages displayed
hasFileInputs
()
Boolean
Returns:
true if the form contains file inputs. These require special treatment when submitting via XHR.
hasMessages
()
Boolean
Returns:
true if there are any messages displayed, of any type
initFocus
()
Set focus to first input field. If a page contains multiple forms, only call this for one of them.
isChanged
()
Boolean
Check if form values have been modified.
Returns:
false if all form elements have the default values passed to the constructor
isFormEnabled
()
Boolean
Returns:
true if form is enabled
notifyErrors
()
Displays a generic message in status_node stating that
the form data failed to validate. Override this if you want to get
fancy.
populateForm
()
Reset all values in the form to the defaults passed to the
constructor or to setDefaultValues().
postPopulateForm
()
Hook for performing additional actions after populateForm()
completes.
postPrepareForm
()
Boolean
Hook called after prepareForm() executes.
Returns:
Return value from this function is returned by prepareForm().
postValidateForm
()
Boolean
Hook called at the end of validateForm(). This is the best place
to put holistic validations that touch multiple form elements.
Returns:
false if validation fails
prepareForm
()
Boolean
Prepare the form for display.
Returns:
true if both pre & post hooks are happy
prePrepareForm
()
Boolean
Hook called before prepareForm() executes.
Returns:
false cancels prepareForm().
registerButton
-
el
Register an object that can be disabled. The object must support the set('disabled', ...) API. (The exception is DOM nodes, since they are automatically wrapped in Y.Node.) Buttons contained within the form DOM element are automatically registered.
Parameters:
-
elString | ObjectThe selector for the element or the element itself
saveCurrentValuesAsDefault
()
Store the current form values in default_value_map.
setDefaultValue
-
field_name -
default_value
Set the default values for a single form element.
Parameters:
-
field_nameStringThe form element name.
-
default_valueString | Int | FloatThe default value.
setDefaultValues
-
default_value_map
Set the default values for all form elements.
Parameters:
-
default_value_mapObject | ModelMapping of form element names to values.
setErrorMessages
-
id -
map
Set the error messages for a form element. This can be used to override the default messages for individual elements
The valid error types are:
requiredmin_length{min}and{max}are replacedmax_length{min}and{max}are replacedinteger{min}and{max}are replaceddecimal{min}and{max}are replacedregex- This
must be set for elements which validate with regular expressions.
Parameters:
-
idString | ObjectThe selector for the element or the element itself
-
mapObjectMap of error types to error messages.
setFormEnabled
-
enabled
Set the enabled state all the registered buttons.
Parameters:
-
enabledBooleantrueto enable the form,falseto disable the form
setFunction
-
id -
f
Set the validation function for a form element.
Parameters:
-
idString | ObjectThe selector for the element or the element itself
-
fFunction | String | ObjectThe function to call after basic validations succeed. If this is a String, it is resolved in the scope of the FormManager object. If this is an object, it must be
{fn:, scope:}. The function will then be invoked in the specified scope.
setRegex
-
id -
regex -
flags
Set the regular expression used to validate the field value.
Since there is no default message for failed regular
expression validation, this function will complain if you have not
already called setErrorMessages() or
addErrorMessage to specify an error message.
Parameters:
-
idString | ObjectThe selector for the element or the element itself
-
regexString | RegExpThe regular expression to use
-
flagsStringIf regex is a String, these are the flags used to construct a RegExp.
setStatusNode
-
node
Parameters:
-
nodeString | Y.Nodethe node in which status should be displayed
statusTakesPrecedence
-
orig_status -
new_status
Compare two status values.
Parameters:
-
orig_statusStringThe name of the original status value.
-
new_statusStringThe name of the new status value.
Returns:
true if new_status takes precedence over orig_status
validateForm
()
Boolean
Returns:
true if all validation checks passed
validateFromCSSData
-
e -
[msg_list]
Validate an input based on its CSS data.
Parameters:
-
eElement | NodeThe field to validate.
-
[msg_list]Map optionalMap of message types to custom messages.
Returns:
Status
- keepGoing
- (Boolean)
trueif further validation should be done. - error
- (String) The error message, if any.
Properties
decimal_value_re
RegExp
static
Regular expression used to determine if a value is a decimal number. This can be localized, e.g., use the correct decimal separator.
field_marker_class
String
The CSS class which marks each field in a row of the form. This enables messaging when multiple fields are in a single row.
integer_value_re
RegExp
static
Regular expression used to determine if a value is an integer. This can be localized, e.g., allow for thousands separator.
row_marker_class
String
The CSS class which marks each row of the form. Typically, each field (or a very tightly coupled set of fields) is placed in a separate row.
row_status_prefix
String
The prefix for all CSS classes placed on a form row when pre-validation
fails. The full CSS class is formed by appending the value from
Y.FormManager.status_order.
status_failure_class
String
The CSS class placed on status_node when
displayFormMessage() is called with
error=true.
status_marker_class
String
The CSS class which marks the container for the status message within a row of the form.
status_none_class
String
The CSS class placed on status_node when it is empty.
status_order
Array
static
Names of supported status values, highest precedence first.
This is static because it links to CSS rules that define the appearance of each status type: .formmgr-has{status}
Default: [ 'error', 'warn', 'success', 'info' ]
status_success_class
String
The CSS class placed on status_node when
displayFormMessage() is called with
error=false.
Strings
Object
static
Map of localizable strings used by pre-validation.
- validation_error
- Displayed in
status_nodebynotifyErrors()when pre-validation fails. - required_string
- Displayed when
yiv-requiredfails on an input field. - required_menu
- Displayed when
yiv-requiredfails on a select element. - length_too_short, length_too_long, length_out_of_range
- Displayed when
yiv-lengthfails on an input field. - integer, integer_too_small, integer_too_large, integer_out_of_range
- Displayed when
yiv-integerfails on an input field. - decimal, decimal_too_small, decimal_too_large, decimal_out_of_range
- Displayed when
yiv-decimalfails on an input field.