Champ:ref:

Ci-dessous la liste des fonctions utilisables avec une instance de champ :

Fonction Description
addActivationCondition() Rajouter une condition d'activation.
addActivationConditionForValidator() Rajouter une condition d'activation pour une règle de validation.
addValidation() Rajouter une règle de validation.
checkActivationCondition() Vérifier l'activation d'un champ.
checkActivationConditionForValidator() Vérifier l'activation d'un validateur d'un champ.
getActivatedValidationRules() Récupérer les règles de validation actives.
getConfiguration() Récupérer la configuration du champ.
getElement() Récupérer l'élément DOM du champ.
getElements() Récupère la configuration complète.
getMessageListContainer() Récupérer l'élément DOM du conteneur de messages de validation.
getErrors() Récupérer les erreurs.
getFieldContainer() Récupérer le conteneur du champ.
getForm() Récupérer le formulaire parent.
getLastValidationErrorName() Récupérer le nom de la dernière erreur de validation.
getMessageTemplate() Récupérer le modèle de message.
getName() Récupérer le nom du champ.
getValue() Récupérer la valeur du champ.
handleLoadingBehaviour() Gérer le comportement de chargement.
hasError() Vérifier la présence d'une erreur.
insertErrors() Insérer des erreurs.
isValid() Vérifier la validité du champ.
isValidating() Vérifier que le processus de validation du champ tourne.
onError() Détecter une erreur de validation.
onValidationBegins() Détecter le lancement de la validation.
onValidationDone() Détecter la fin de la validation.
refreshMessages() Vider le conteneur de messages.
validate() Lancer le processus de validation.
wasValidated() Le champ a été validé.

Rajouter une condition d'activation:ref:

Fonction

addActivationCondition(name, callback)

Retour

/

Paramètres

  • name (String) : nom arbitraire de la condition d'activation.
  • callback (Function) : la fonction qui sera appelée lorsque la condition d'activation sera lancée.

Description

Rajoute une condition d'activation pour le champ. Le fonctionnement est le suivant : lorsque JavaScript tente de valider le champ, il va boucler sur toutes les conditions d'activation enregistrées pour ce champ, et exécuter la fonction contenue dans callback. Si au moins l'une d'entre elles retourne false, alors le champ sera considéré comme désactivé.

La fonction callback contiendra deux paramètres :

  • field : l'instance du champ qui est en train d'être vérifié ;
  • continueValidation : une fonction qui devra impérativement être appelé dans votre fonction, et qui contiendra un seul et unique paramètre : un booléen qui indiquera si oui ou non le champ est désactivé.

Avertissement

Soyez certain que continueValidation est appelé à coup sûr, cela peut entraîner d'énormes dysfonctionnements si ce n'est pas le cas.

Attention

Notez bien que si vous agissez avec JavaScript sur les situations dans lesquelles des champs sont (dés)activés, il faudra très probablement que vous fassiez en sorte d'avoir le même comportement côté serveur, dans le Validateur de formulaire, grâce aux fonctions deactivateField($fieldName) et activateField($fieldName).

Exemple :

form.getFieldByName('email').addActivationCondition(
    'customConditionEmail',
    function (field, continueValidation) {
        var flag = true;

        if (jQuery('#some-random-element').hasClass('test')) {
            flag = false;
        }

        continueValidation(flag);
    }
);

Indice

Vous pouvez rajouter autant de conditions d'activation que souhaité.

Note

Cette fonction est appelée par le cœur de FormZ, dans du code généré automatiquement à partir des valeurs contenus dans la configuration TypoScript des conditions d'activations de champs.

Rajouter une condition d'activation pour une règle de validation:ref:

Fonction

addActivationConditionForValidator(name, validationName, callback)

Retour

/

Paramètres

  • name (String) : nom arbitraire de la condition d'activation.
  • validationName (String) : le nom de la règle de validation à laquelle rajouter la condition d'activation.
  • callback (Function) : la fonction qui sera appelée lorsque la condition d'activation sera lancée.

Description

Il s'agit du même principe qu'au dessus, mais cette fois-ci pour une règle de validation.

Par exemple, un champ peut contenir deux règles de validation, dont l'une peut être désactivée selon certains critères propres à votre environnement.

Attention

Notez bien que si vous agissez avec JavaScript sur les situations dans lesquelles des règles de validations de champs sont (dés)activés, il faudra très probablement que vous fassiez en sorte d'avoir le même comportement côté serveur, dans le Validateur de formulaire, grâce aux fonctions deactivateFieldValidator($fieldName, $validatorName) et activateFieldValidator($fieldName, $validatorName).

Dans l'exemple ci-dessous, on agit sur la règle required du champ email. Il se peut donc que cette règle soit désactivée à certains moments ; pour autant un champ email aura probablement une autre règle isEmail qui vérifiera que la valeur est une adresse email valide : cette règle devra toujours être activée.

Exemple :

form.getFieldByName('email').addActivationConditionForValidator(
    'customConditionEmailRequired',
    'required',
    function (field, continueValidation) {
        var flag = true;

        if (customFunctionToCheckIfFieldsAreRequired()) {
            flag = false;
        }

        continueValidation(flag);
    }
);

Indice

Vous pouvez rajouter autant de conditions d'activation que souhaité.

Note

Cette fonction est appelée par le cœur de FormZ, dans du code généré automatiquement à partir des valeurs contenus dans la configuration TypoScript des conditions d'activations de règles de validation.


Rajouter une règle de validation:ref:

Fonction

addValidation(validationName, validatorName, validationConfiguration)

Retour

/

Paramètres

  • validationName (String) : le nom de la règle (son index), doit être unique pour ce champ.
  • validatorName (String) : le nom du validateur utilisé pour cette règle. Cela doit être un validateur existant, rajouté via Fz.Validation.registerValidator().
  • validationConfiguration (Object) : la configuration du validateur, qui lui sera transmise lorsque la validation sera lancée.

Description

Rajoute une règle de validation au champ.

Il est ensuite possible de manipuler cette règle avec la fonction addActivationConditionForValidator().


Vérifier l'activation d'un champ:ref:

Fonction

checkActivationCondition(runValidationCallback, stopValidationCallback)

Retour

/

Paramètres

  • runValidationCallback (Function) : fonction qui sera appelée si le champ est activé.
  • stopValidationCallback (Function) : fonction qui sera appelée si le champ est désactivé.

Description

Cette fonction vous permet de vérifier que le champ est actuellement activé, ou non.

Selon s'il est activé ou non, une des deux fonctions passées en paramètre sera appelée.

Exemple :

form.getFieldByName('email').checkActivationCondition(
    function() {
        alert('Field is activated!');
    },
    function() {
        alert('Field is deactivated!');
    }
);

Vérifier l'activation d'un validateur d'un champ:ref:

Fonction

checkActivationConditionForValidator(validatorName, runValidationCallback, stopValidationCallback)

Retour

/

Paramètres

  • validatorName (String) : nom du validateur souhaité, par exemple required.
  • runValidationCallback (Function) : fonction qui sera appelée si le validateur est activé.
  • stopValidationCallback (Function) : fonction qui sera appelée si le validateur est désactivé.

Description

Cette fonction vous permet de vérifier qu'un validateur donné du champ est actuellement activé, ou non.

Selon s'il est activé ou non, une des deux fonctions passées en paramètre sera appelée.

Exemple :

form.getFieldByName('email').checkActivationCondition(
    'required',
    function() {
        alert('The field is required!');
    },
    function() {
        alert('The field is not required!');
    }
);

Récupérer les règles de validation actives:ref:

Fonction

getActivatedValidationRules(callback)

Retour

/

Paramètres

  • callback (Function) : fonction qui sera appelée lorsque la liste des règles de validation sera construite.

Description

Fonction permettant de récupérer la liste des règles de validation qui sont actuellement activées pour le champ.

Exemple :

form.getFieldByName('email').getActivatedValidationRules(
    function(activatedRules) {
        if ('required' in activatedRules) {
            // ...
        }
    }
);

Récupérer la configuration du champ:ref:

Fonction

getConfiguration()

Retour

Object

Description

Retourne l'objet de configuration du champ, qui peut contenir certaines informations utiles.


Récupérer l'élément DOM du champ:ref:

Fonction

getElement()

Retour

Element

Description

Retourne l'élément HTML (dans le DOM) du champ.

Attention

Cette fonction est à utiliser pour les champs qui ne contiennent qu'un seul élément, par exemple des champs de type select ou text.

Pour les champs à multiples éléments, comme les checkbox ou radio, utilisez la fonction getElements().


Récupérer les éléments DOM du champ:ref:

Fonction

getElements()

Retour

NodeList

Description

Retourne les éléments HTML (dans le DOM) du champ.

Attention

Cette fonction est à utiliser pour les champs qui contiennent plusieurs éléments, par exemple des champs de type checkbox ou radio.

Pour les champs à élément unique, comme les select ou text, utilisez la fonction getElement().


Récupérer l'élément DOM du conteneur de retours de validation:ref:

Fonction

getMessageListContainer()

Retour

Element

Description

Le conteneur de retours de validation est un bloc qui sera automatiquement mis à jour par JavaScript, qui insérera les messages retournés par les différents validateurs utilisés.

Il est déconseillé d'interagir directement sur le contenu de ce bloc, mais vous pouvez procéder à d'autres opérations comme le rajout de classes, par exemple.

Note

La valeur du paramètre TypoScript settings.messageListSelector sera utilisée pour sélectionner l'élément.


Récupérer les erreurs:ref:

Fonction

getErrors()

Retour

Object

Description

Retourne les erreurs actuelles du champ.

Avertissement

L'appel à cette fonction n'est logique que si le champ a déjà été validé. Référez-vous à la fonction wasValidated() pour plus d'informations.


Récupérer le conteneur du champ:ref:

Fonction

getFieldContainer()

Retour

Element

Description

Retourne l'élément DOM qui contient le gabarit entier du champ.

Note

La valeur du paramètre TypoScript settings.fieldContainerSelector sera utilisée pour sélectionner l'élément.


Récupérer le formulaire parent:ref:

Fonction

getForm()

Retour

Fz.FullForm

Description

Retourne l'instance du formulaire dont fait partie ce champ.


Récupérer le nom de la dernière erreur de validation:ref:

Fonction

getLastValidationErrorName()

Retour

String

Description

Retourne le nom de la dernière règle de validation qui a renvoyé une erreur lors de la validation du champ.


Récupérer le modèle de message:ref:

Fonction

getMessageTemplate()

Retour

String

Description

Retourne le modèle de message à utiliser lorsqu'un message doit être rajouté dans le conteneur de retours de validation.

Ce modèle peut être récupéré de deux façons :

  1. Via la configuration TypoScript settings.messageTemplate ;
  2. Via le bloc HTML.

Récupérer le nom du champ:ref:

Fonction

getName()

Retour

String

Description

Retourne le nom du champ.


Récupérer la valeur du champ:ref:

Fonction

getValue()

Retour

String|Array

Description

Retourne la valeur actuelle du champ.

Le type de retour diffère selon le type du champ. S'il s'agit d'un champ « simple » avec un seul élément (par exemple select ou text), alors la valeur de ce champ sera renvoyée. En revanche, pour les champs « multiples » tels que checkbox ou radio, un tableau contenant les valeurs sélectionnées sera retourné.


Gérer le comportement de chargement:ref:

Fonction

handleLoadingBehaviour(run)

Retour

/

Paramètres

  • run (Boolean) : true si le comportement de chargement doit être chargé, sinon false.

Description

Activate ou désactive le comportement de chargement du champ. Concrètement, une classe CSS est ajoutée au conteneur du champ, ce qui permet de rajouter facilement en CSS un aspect visuel de chargement, comme un cercle de chargement à côté du champ en question.

Par défaut, ce comportement est lancé lorsque la validation du champ commence, puis est stoppé lorsque la validation est terminée.

Vous pouvez manipuler ce comportement à votre guise si vous effectuez des opérations « lourdes » sur votre champ, et que vous souhaitez indiquer à l'utilisateur que le processus est lancé (très utile pour les requêtes Ajax par exemple).


Vérifier la présence d'une erreur:ref:

Fonction

hasError(validationName, errorName)

Retour

Boolean

Paramètres

  • validationName (String) : nom de la règle de validation qui contiendrait une erreur.
  • errorName (String) : nom de l'erreur recherchée, couramment default. Si la valeur donnée est null, n'importe quelle erreur trouvée pour la règle de validation sera comptée.

Description

Vérifie la présence d'une certaine erreur pour le champ.


Insérer des erreurs:ref:

Fonction

insertErrors(errors)

Retour

/

Paramètres

  • errors (Objet) : liste des erreurs à insérer dans le conteneur de messages.

Description

Insère des erreurs dans le conteneur de messages. La liste des erreurs est un objet dont le premier niveau représente le nom de la règle de validation, et le deuxième niveau le nom de l'erreur.

Exemple :

var errors = {customRule: {message: 'hello world!'}};
form.getFieldByName('email').insertErrors(errors);

Vérifier la validité du champ:ref:

Fonction

isValid()

Retour

Boolean

Description

Vérifie que le champ est valide.

Avertissement

L'appel à cette fonction n'est logique que si le champ a déjà été validé. Référez-vous à la fonction wasValidated() pour plus d'informations.


Vérifier que le processus de validation du champ tourne:ref:

Fonction

isValidating()

Retour

Boolean

Description

Renvoie true si le processus de validation de ce champ est actuellement en train de tourner.


Détecter une erreur de validation:ref:

Fonction

onError(validationName, errorName, callback)

Retour

/

Paramètres

  • validationName (String) : nom de la règle de validation qui retournerait l'erreur.
  • errorName (String) : nom de l'erreur retournée, couramment default. Si la valeur donnée est null, n'importe quelle erreur déclenche l'évènement.
  • callback (Function) : fonction appelée lorsque la validation du champ rencontre l'erreur spécifiée par validationName et errorName.

Description

Permet de brancher une fonction sur la rencontre d'une certaine erreur lors de la validation du champ.


Détecter le lancement de la validation:ref:

Fonction

onValidationBegins(callback)

Retour

/

Paramètres

  • callback (Function) : fonction appelée lorsque le processus de validation du champ commence.

Description

Permet de brancher une fonction sur le lancement du processus de validation du champ.


Détecter la fin de la validation:ref:

Fonction

onValidationDone(callback)

Retour

/

Paramètres

  • callback (Function) : fonction appelée lorsque le processus de validation du champ se termine.

Description

Permet de brancher une fonction sur la fin du processus de validation du champ.


Vider le conteneur de messages:ref:

Fonction

refreshMessages()

Retour

/

Description

Vide complètement le conteneur de messages. Vous pouvez insérer de nouveaux messages avec la fonction « insertErrors(errors) ».


Lancer le processus de validation:ref:

Fonction

validate()

Retour

/

Description

Lance le processus de validation du champ.

Il est possible de se brancher sur le lancement de la validation avec la fonction onValidationBegins(), et sur la fin de la validation avec la fonction onValidationDone().


Le champ a été validé:ref:

Fonction

wasValidated()

Retour

Boolean

Description

Retourne true si le champ a déjà fini un processus de validation au moins une fois.

Cette fonction est notamment utile pour toutes les autres fonctions qui dépendent du résultat de la validation, comme la fonction isValid().