DEPRECATION WARNING
This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.
Field¶
You can find below the list of available function for a field instance:
| Function | Description |
|---|---|
| addActivationCondition() | Add an activation condition. |
| addActivationConditionForValidator() | Add an activation condition to a given validation rule. |
| addValidation() | Add a validation rule. |
| checkActivationCondition() | Check a field activation. |
| checkActivationConditionForValidator() | Check the activation of a field validator. |
| getActivatedValidationRules() | Get the currently active validation rules. |
| getConfiguration() | Fetch the configuration of a field. |
| getElement() | Fetch the DOM element of a field. |
| getElements() | Get the complete configuration. |
| getMessageListContainer() | Fetch the DOM element of the validation message container. |
| getErrors() | Get the errors. |
| getFieldContainer() | Fetches the container of a field. |
| getForm() | Get the parent form. |
| getLastValidationErrorName() | Get the last validation error name. |
| getMessageTemplate() | Get the message template. |
| getName() | Get the name of a field. |
| getValue() | Get the value of a field. |
| handleLoadingBehaviour() | Handle the loading behaviour. |
| hasError() | Check if there is an error. |
| insertErrors() | Insert errors. |
| isValid() | Check if a field is valid. |
| isValidating() | Check if the field validation process is currently running. |
| onError() | Hook at a validation error. |
| onValidationBegins() | Hook at the validation beginning. |
| onValidationDone() | Hook at the validation end. |
| refreshMessages() | Empty the message container. |
| validate() | Launch the validation process. |
| wasValidated() | Check if the field was validated. |
Add an activation condition¶
Function
addActivationCondition(name, callback)
Return
/
Parameters
name(String): arbitrary name of the activation condition.callback(Function): the function which is called when the activation condition runs.
Description
Adds an activation condition for this field. It works like this: when JavaScript tries to validate a field, it will loop on all registered activation conditions for this field, and execute the function in callback. If at least one of them returns false, the field is considered as deactivated.
The function callback has two parameters:
field: the field instance which is currently validated;continueValidation: a function which must be called in your function, and contain one parameter only: a boolean which tells if the field is deactivated or not.
Warning
Be sure that continueValidation is called no matter what, it could lead to huge issues if you don't.
Attention
Note that if you work with JavaScript on situations where fields are (de)activated, you must probably do the same on the server side, in the Form validator, thanks to the functions deactivateField($fieldName) and activateField($fieldName).
Example:
form.getFieldByName('email').addActivationCondition(
'customConditionEmail',
function (field, continueValidation) {
var flag = true;
if (jQuery('#some-random-element').hasClass('test')) {
flag = false;
}
continueValidation(flag);
}
);
Hint
You can add as many activation conditions as you want.
Note
This function is used by FormZ core, in code automatically generated from values written in the TypoScript configuration of the fields activation conditions.
Add an activation condition to a validation rule¶
Function
addActivationConditionForValidator(name, validationName, callback)
Return
/
Parameters
name(String): arbitrary name of the activation condition.validationName(String): name of the validation rule onto which the activation condition is bound.callback(Function): the function which is called when the activation condition runs.
Description
It's the same as above, but for a validation rule.
For example, a field may have two validation rules, one of which can be deactivated depending on criteria of your own environment.
Attention
Note that if you work with JavaScript on situations where validation rules are (de)activated, you must probably do the same on the server side, in the Form validator, thanks to the functions deactivateFieldValidator($fieldName, $validatorName) and activateFieldValidator($fieldName, $validatorName).
In the example below, we manipulate the rule required of the field email. There can be a situations where this rule is deactivated, but the field will still have another rule isEmail which checks that the value is a correct email address, and is always activated.
Example:
form.getFieldByName('email').addActivationConditionForValidator(
'customConditionEmailRequired',
'required',
function (field, continueValidation) {
var flag = true;
if (customFunctionToCheckIfFieldsAreRequired()) {
flag = false;
}
continueValidation(flag);
}
);
Hint
You can add as many activation conditions as you want.
Note
This function is used by FormZ core, in code automatically generated from values written in the TypoScript configuration of the validation rules activation conditions.
Add a validation rule¶
Function
addValidation(validationName, validatorName, validationConfiguration)
Return
/
Parameters
validationName(String): name of the rule (its index), must be unique for this field.validatorName(String): name of the validator used for this rule. It must be an existing validator, registered with Fz.Validation.registerValidator().validationConfiguration(Object): configuration of the validator, which will be sent when validation begins.
Description
Adds a validation rule to the field.
It's then possible to manipulate this rule with the function addActivationConditionForValidator().
Check a field activation¶
Function
checkActivationCondition(runValidationCallback, stopValidationCallback)
Return
/
Parameters
runValidationCallback(Function): function called if the field is activated.stopValidationCallback(Function): function called if the field is deactivated.
Description
This function checks if a field is currently activated, or not.
Depending if the field is activated or not, one of the two parameters functions is called.
Example:
form.getFieldByName('email').checkActivationCondition(
function() {
alert('Field is activated!');
},
function() {
alert('Field is deactivated!');
}
);
Check a field validator activation¶
Function
checkActivationConditionForValidator(validatorName, runValidationCallback, stopValidationCallback)
Return
/
Parameters
validatorName(String): name of the wanted validator, for instancerequired.runValidationCallback(Function): function called if the validator is activated.stopValidationCallback(Function) : function called if the validator is deactivated.
Description
This function checks if a given validator for the field is currently activated, or not.
Depending if the validator is activated or not, one of the two parameters functions is called.
Example:
form.getFieldByName('email').checkActivationCondition(
'required',
function() {
alert('The field is required!');
},
function() {
alert('The field is not required!');
}
);
Get currently active validation rules¶
Function
getActivatedValidationRules(callback)
Return
/
Parameters
callback(Function): function called when the validation rules list is built.
Description
Function allowing to fetch the list of currently active validation rules for the field.
Example:
form.getFieldByName('email').getActivatedValidationRules(
function(activatedRules) {
if ('required' in activatedRules) {
// ...
}
}
);
Get the field configuration¶
Function
getConfiguration()
Return
Object
Description
Returns the configuration object of the field, which may contain some useful data.
Get the field DOM element¶
Function
getElement()
Return
Element
Description
Returns the HTML element (in the DOM) of the field.
Attention
This function must be used only for fields that contain a unique element, for instance the fields of type select or text.
For fields containing several elements, like checkbox or radio, use the function getElements().
Get the field DOM elements¶
Function
getElements()
Return
NodeList
Description
Returns the HTML elements (in the DOM) of the field.
Attention
This function must be used for fields that contain several elements, for instance the fields of type checkbox or radio.
For fields containing a unique element, like select or text, use the function getElement().
Get the DOM element of the message list container¶
Function
getMessageListContainer()
Return
Element
Description
The message container is a block which is automatically updated by JavaScript, which will insert the messages returned by the used validators.
It's not recommended to interact directly with the content of this block, but you may proceed to other operations like add classes for instance.
Note
The value of the TypoScript parameter settings.messageListSelector is used to select the element.
Get the errors¶
Function
getErrors()
Return
Object
Description
Returns the current field's errors.
Warning
Calling this function makes sense only when the field has been validated. Check the function wasValidated() for further information.
Get the field container¶
Function
getFieldContainer()
Return
Element
Description
Returns the DOM element which contains the entire field template.
Note
The value of the TypoScript parameter settings.fieldContainerSelector is used to select the element.
Get the parent form¶
Function
getForm()
Return
Fz.FullForm
Description
Returns the form instance from which this field comes.
Get the last validation error name¶
Function
getLastValidationErrorName()
Return
String
Description
Returns the name of the last validation rule which returned an error during the field validation.
Get the message template¶
Function
getMessageTemplate()
Return
String
Description
Returns the message template which is used when a message is added in the message list container.
This template can be fetched using two ways:
- With the TypoScript configuration settings.messageTemplate ;
- With the HTML block.
Get the field value¶
Function
getValue()
Return
String|Array
Description
Returns the current value of the field.
The return type may differ depending on the field type. If it is a “unique” field with one element (for instance select or text), then the value of this field is returned. But for “multiple” fields (for instance checkbox or radio), an array containing the selected values is returned.
Handle the loading behaviour¶
Function
handleLoadingBehaviour(run)
Return
/
Parameters
run(Boolean):trueif the loading behaviour is triggered, otherwisefalse.
Description
Activates or deactivates the loading behaviour of the field. A CSS class is added to the field container, which allows to easily add a loading effect, like an animated loading circle next to the field.
By default, this behaviour is triggered when the field validation process begins, and is stopped when the validation is done.
You may manipulate this behaviour as you like if you do heavy operations on your field, and you want to indicate to the user that the process is running (very useful for Ajax request for instance).
Check if the field has an error¶
Function
hasError(validationName, errorName)
Return
Boolean
Parameters
validationName(String): name of the validation rule which may contain an error.errorName(String): name of the wanted error, usuallydefault. If the given value isnull, any error found for this validation rule will match.
Description
Checks if the field has a given error.
Insert errors¶
Function
insertErrors(errors)
Return
/
Parameters
errors(Object): list of errors to be inserted in the message container.
Description
Insert errors in the message container. The error list is an object, for which each key is the name of a validation rule, the second key is the name of the error and the value is the error message.
Example:
var errors = {customRule: {message: 'hello world!'}};
form.getFieldByName('email').insertErrors(errors);
Check if the field is valid¶
Function
isValid()
Return
Boolean
Description
Checks if the field is valid.
Warning
Calling this function makes sense only when the field has been validated. Check the function wasValidated() for further information.
Check if the field validation process is currently running¶
Function
isValidating()
Return
Boolean
Description
Returns true if the field validation process is currently running.
Spot a validation error¶
Function
onError(validationName, errorName, callback)
Return
/
Parameters
validationName(String): name of the validation rule which returns an error.errorName(String): name of the returned error, usuallydefault. If the given value isnull, any error found for this validation rule will trigger the event.callback(Function): function called when the field validation encounters the error specified byvalidationNameanderrorName.
Description
Allows connecting a function on the event triggered when a given error is found during the field validation.
Spot the validation beginning¶
Function
onValidationBegins(callback)
Return
/
Parameters
callback(Function): function called when the field validation process begins.
Description
Allows hooking a function at the beginning of the field validation process.
Spot the validation ending¶
Function
onValidationDone(callback)
Return
/
Parameters
callback(Function): function called when the field validation process ends.
Description
Allows hooking a function at the end of the field validation process.
Empty message container¶
Function
refreshMessages()
Return
/
Description
Completely empty the message container. You may insert new messages with the function “insertErrors(errors)”.
Launch the validation process¶
Function
validate()
Return
/
Description
Launches the field validation process.
It's possible to hook a function at the beginning of the validation process with the function onValidationBegins(), and on the end of the validation process with the function onValidationDone().