Formulaires


    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
      });
    

    Un formulaire d’indexation permet la visualisation et la modification des tags d’un composant. Afin de pouvoir intéragir avec ce type de formulaire, il est nécessaire de s’abonner à son ouverture :

    JSAPI.get().registerForComponentChange(function(componentFormAPI, component, phase) {
    	// Utilisation de l'objet componentFormAPI permettant d'intéragir avec le formulaire
    });
    

    Nota : Dans le cas de l’affichage de plusieurs formulaires de composant, il peut être nécessaire d’accéder à un formulaire en particulier : JSAPI.get().getComponentFormAPI(<identifiant du composant>). Il est également possible d’accéder au dernier formulaire grâce à JSAPI.get().getLastComponentFormAPI().

    Actions dans un formulaire

    L’objet componentFormAPI.getActions() permet d’intéragir avec les actions d’un formulaire présentant un document, dossier…

    Pour cela plusieurs fonctions sont exposées.

    Fonctions Description
    getHeaderActions() Récupère le conteneur d’action dans l’en-tête
    getTaskActions() Récupère le conteneur d’action des tâches
    getFooterActions() Récupère le conteneur d’action dans le pied de page (validation, annulation…)

    Afin d’intéragir avec les actions récupérées depuis les 3 conteneurs d’actions, les fonctions disponibles sont documentées dans la partie Actions. Si le but est d’intéragir avec les différents conteneurs d’actions, pour, par exemple, leurs ajouter des action les fonctions disponibles sont documentées dans la sous-partie Actions.

    Ajout de cartes

    Un formulaire d’indexation est composé d’un ensemble de carte contenant les informations du composant, les tags, pièces jointes et dossiers parent. Il est également possible d’ajouter des cartes grâce à l’API JS avec la fonction addCardContainer(cardContainer) qui nécessite une carte de type conteneur en entrée.

    Les fonctions disponibles sur cet objet sont disponible dans la partie Cartes.

    Exemple : ajout de carte conteneur personnalisée

    var formAPI = JSAPI.get().getLastComponentFormAPI();
    
    var desc1 = buildDescription("Description 1");
    var card1 = buildCard("Card", "Heading card", "card-style");
    
    var div = document.createElement("div");
    div.className="custom-card-container";
    addChildren(div, [desc1,card1]);
    
    var cardContainer = buildCardContainer("fa fa-clone","Title","Caption","card-box custom-card-container");
    cardContainer.setContent(div);
    formAPI.addCardContainer(cardContainer);
    
    function buildCardContainer(icon,title,caption, style){
    	var cardContainer = new CardContainer();
    	cardContainer.setIcon(icon);
    	cardContainer.setTitle(title);
    	cardContainer.setCaption(caption);
    	cardContainer.setVisible(true);
    	cardContainer.addStyle(style);
    	return cardContainer;
    }
    function buildDescription(description){
    	var desc = document.createElement("div");
    	desc.innerHTML = description;
    	return desc;
    }
    function buildCard(title, heading, style){
    	var card = new Card();
    	card.setTitle(title);
    	card.setHeading(heading);
    	card.addStyle(style);
    	return card.asElement();
    }
    function addChildren(parent, children){
    	for (i=0; i < children.length; ++i) {
        	parent.appendChild(children[i]);
    	}
    }
    

    Un formulaire de recherche permet la saisie de critères permettant aux utilisateurs d’accéder facilement aux composants stockés. Afin de pouvoir intéragir avec ce type de formulaire, il est nécessaire de s’abonner à son ouverture :

    JSAPI.get().registerForSearchOpen(function(searchFormAPI, template) {
    	console.log("hidden request: " + searchFormAPI.getHiddenRequest());
    });
    

    Un formulaire de recherche dispose de deux conteneurs d’actions disponible grâce aux fonctions suivantes :

    Fonction Description
    getHeaderActions() Récupère le conteneur d’action au dessus des résultats de recherche
    getFooterActions() Récupère le conteneur d’action en dessous des résultats de recherche

    L’exemple ci-dessous illustre l’ajout d’une action dans le conteneur sous le tableau de résultats.

    JSAPI.get().registerForSearchOpen(function(searchFormAPI, template) {
    	console.error("Call of register for open");
    	var actionAPI = JSAPI.get().getActionFactoryAPI();
    	var action = actionAPI.buildTextual("myCustomAction", "Test", function(actionPresenter){
    		console.info("on click");
    		actionPresenter.setEnabled(false);
    	});
    
    	var footerActions = searchFormAPI.getFooterActions();
    	footerActions.remove(action.getId());
    	footerActions.add(action);
    });
    

    Si l’on souhaite réagir au changement de valeur d’un critère de recherche spécifique, l’abonnement s’effectue comme ci-dessous :

    criterionName = "EDS";
    JSAPI.get().getSearchFormAPI().registerForCriterionChange(criterionName, function(criterion) {
    });
    

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

    Les fonctions disponibles sur l’API de réponses avec motifs sont :

    Fonction Description
    getPopup() Récupère la popup de réponse
    registerForFieldChange(fieldName, callback) Permet l’abonnement à la modification d’un champ dans la popup de réponse
    getReasonedAnswerId() Récupère l’identifiant de la réponse
    getTasks() Récupère la liste des tâches associées à la réponse

    Exemples :

    JSAPI.get().registerForReasonedAnswerOpen(function(reasonedAnswerAPI, reasonedAnswerId) {
    	console.log("Opened reasoned answer Id : " + reasonedAnswerAPI.getReasonedAnswerId());
    });
    
    JSAPI.get().getLastReasonedAnswerAPI().registerForFieldChange("Comments", function(fieldName, fieldValue) {
        console.log("Value of " + fieldName + " changed to : " + fieldValue);
    });
    

    A noter : Dans cette partie, la variable reasonedAnswerId permet d’utiliser l’identifiant la réponse venant d’être ouverte

    Attention : Dans le cas de l’affichage de plusieurs formulaires de réponses avec motifs, il peut être nécessaire d’accéder à un formulaire en particulier : JSAPI.get().getReasonedAnswerAPI(<identifiant de la réponse>). Il est également possible d’accéder au dernier formulaire grâce à JSAPI.get().getLastReasonedAnswerAPI().

    Résumé

    Le résumé des pièces jointes peut être surchargé à l’aide de l’API TaskAttachmentSynopsisHelper.

    Définir le résumé d’une pièce basé sur les tags de la tâche parente :

    helper = JSAPI.get().getHelperFactory().getTaskAttachmentSynopsisHelper();
    helper.register(function(task, definition, attachedComponent, callback){
    	new TemplateResolver("TASK").resolveTemplate(task, "${Priority}", function(resolved){
    	    console.log("Resolved template: " + resolved); 
    	    callback.onSuccess(resolved);
    	});
    });
    

    Définir le résumé d’une pièce jointe non-renseignée` :

    helper = JSAPI.get().getHelperFactory().getTaskAttachmentSynopsisHelper();
    helper.register(function(task, definition, attachedComponent, callback){
    	if(!attachedComponent){
    		callback.onSuccess("Pièce à définir");
    	}
    	else{
    		//Utilisation du résumé défini pas défaut
    		callback.onSuccess();
    	}
    });