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 instance required.
  • 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:

  1. With the TypoScript configuration settings.messageTemplate ;
  2. With the HTML block.

Get the field name

Function

getName()

Return

String

Description

Returns the name of the field.


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): true if the loading behaviour is triggered, otherwise false.

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, usually default. If the given value is null, 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, usually default. If the given value is null, any error found for this validation rule will trigger the event.
  • callback (Function): function called when the field validation encounters the error specified by validationName and errorName.

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().


Check if the field was validated

Function

wasValidated()

Return

Boolean

Description

Returns true if the field has finished at least once a validation process.

This function is useful for other functions which depend on the result of the validation, like the function isValid().