Interactions avec les champs


Les formulaires sont la base des écrans présentés au sein de l’interface graphique. Cette section liste comment acquérir un objet de type formAPI permettant d’intéragir avec un formulaire et les fonctions associées.

Les champs simples

A noter : Dans cette partie, la variable fieldName correspond dans le cas d’un tag à la valeur de son identifiant. S’il s’agit de la classe du composant, il faut utiliser Class.

Fonctions Description
hasField(fieldName) Permet de déterminer si le champ existe dans le formulaire
setObjectValue(fieldName, fieldValue) Modifie la valeur d’un champ
getObjectValue(fieldName) Récupère la valeur d’un champ
suggest(fieldName, suggestions) Affiche une liste de suggestion sur un champ STRING
setDescription(fieldName, description) Modifie la valeur de la description d’un champ

Quelques exemples :

  • Modification d’un tag EndDate de type TIMESTAMP :

    // Définition de la valeur à partir d'un objet Date
    formAPI.setObjectValue("EndDate",new Date(2016,11,04));
    // Définition à partir d'un timestamp (nombre de millisecondes écoulées depuis le 01/01/1970)
    formAPI.setObjectValue("EndDate", 0);
    
  • Modification d’un tag Received de type BOOLEAN :

    // Définition de la valeur à partir d'un booléen
    formAPI.setObjectValue("Received",true);
    
  • Modification de l’identifiant de la classe :

    formAPI.setObjectValue("Class", "Document");
    

Suggestion de valeurs

Afin de suggérer à l’utilisateur des valeurs pour un champ, il est possible d’utiliser la fonction suggest(fieldName, suggestions).

Les suggestions à passer en paramètre sont composées d’un nom symbolique (setValue(symbolicName)) et d’un libellé (setName(displayName)). Ainsi si l’utilisateur sélectionne une des suggestions, le formulaire sera soumis avec le nom symbolique.

function buildSuggestion(name, value){
	var suggestion = new LookupResult();
	suggestion.setName(name);
	suggestion.setValue(value);
	return suggestion;
}

var suggestions = new Array();	
suggestions[0] = buildSuggestion("name1", "value1");
suggestions[1] = buildSuggestion("name2", "value2");
formAPI.suggest("MailObject", suggestions);

Les listes de choix

Fonctions Description
getAllowedValues(fieldName) Récupère l’ensemble des valeurs autorisées pour un champ de type CHOICELIST
setAllowedValues(fieldName, allowedValues) Modifie les valeurs autorisées pour un champ de type CHOICELIST
function buildAllowedValue(symbolicName, label) {
	var language = new Language("EN");

	var allowedValue = new AllowedValueDefinition();
	allowedValue.setSymbolicName(symbolicName);

	var displayNames = new I18NLabel()
	displayNames.setLabel(language, label);
	allowedValue.setDisplayNames(displayNames);
	return allowedValue;
}

var restrictedAllowedValues = new Array();
restrictedAllowedValues[0] = buildAllowedValue("symbolicName1", "firstLabel");
restrictedAllowedValues[1] = buildAllowedValue("symbolicName2", "secondLabel");

formAPI.setAllowedValues("BillType", restrictedAllowedValues);

Etat des champs

Plusieurs fonctions permettent de changer l’état d’un champ au sein d’un formulaire. Elles s’utilisent avec les paramètres :

  • fieldName correspondant à l’identifiant du champs
  • boolean correspondant à l’activation de l’état
Fonctions Description
setReadOnly(fieldName, isReadOnly) Définit si le champ est lecture seule ou non
getTagValidity(fieldName) Récupère la validité d’un champ
setValid(fieldName, valid) Modifie la validité d’un champ. Si le paramètre valid est
false alors la soumission du formulaire ne pourra être validée
setVisible(fieldName, isVisible) Définit si le champ est visible ou masqué

Changer la visibilité d’un champ d’un formulaire d’indexation :

formAPI.setVisible("BillType", false);

Abonnement au changement de validité d’un formulaire

Différentes fonctions permettent de s’abonner au changement de validité d’un formulaire en fonction du besoin :

  • Validité du formulaire complet, à savoir, les champs et le contenu :

    formAPI.registerForValidity(function(isValid, invalidFields, invalidTypes){
    	console.log("Component is valid=" + isValid + ", invalidFields=" + invalidFields + ", invalidTypes=" + invalidTypes);
    })
    
  • Validité partiel du formulaire :

Cette fonction permet de s’abonner uniquement à la validité d’une partie du formulaire, soit les champs (FIELDS), soit le contenu (CONTENT).
Dans l’exemple suivant, on s’abonne uniquement au changement de validité des champs.

formAPI.registerForPartialValidity("FIELDS", function(isValid, type, invalidFields){
	console.log("Component is valid=" + isValid + ", invalidFields=" + invalidFields + ", type=" + type);
})


Les fonctions suivantes sont également à disposition pour connaitre l’état du formulaire courant :

Fonctions Description
getInvalidType(type) Récupère la validité à partir du nom d’une partie de formulaire : FIELDS pour les champs invalides ou CONTENT pour le contenu / pièces jointes invalides
getInvalidTypes() Récupère les noms de parties invalides du formulaire

Lister les champs d’un formulaire

La fonction formAPI.getFields() sur un formulaire permet de récupérer la liste des identifiants des champs présents dans ce formulaire.

Changement de valeur

Pour fournir à vos utilisateurs des formulaires intéractifs, il est possible de s’abonner aux changements de valeur d’un champ afin de modifier son état ou modifier un autre champ.

  formAPI.registerForFieldChange("Montant", function(fieldName, fieldValue){
	// Utilisation de la nouvelle valeur d'un champ
  });