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’interagir avec un formulaire et les fonctions associées.

    Les champs simples

    Note : 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.

    Fonction 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

    Fonction 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 champ
    • boolean correspondant à l’activation de l’état
    Fonction Description
    setReadOnly(fieldName, isReadOnly) Définit si le champ est en 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 pas être validée
    setVisible(fieldName, isVisible) Définit si le champ est visible ou masqué

    Exemple : 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é partielle 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 connaître l’état du formulaire courant :

    Fonction 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 interactifs, 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 interagir 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'interagir avec le formulaire
    });
    

    Note : 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’interagir avec les actions d’un formulaire présentant un document, dossier…

    Pour cela, plusieurs fonctions sont exposées.

    Fonction 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…)

    La partie Actions documente les fonctions disponibles permettant d’intéragir avec les différents conteneurs d’actions ainsi qu’avec les actions récupérées depuis ces 3 contenurs.

    Ajout de cartes

    Un formulaire d’indexation est composé d’un ensemble de cartes contenant les informations du composant, les tags, pièces jointes et dossiers parents. 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 disponibles 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]);
    	}
    }
    

    Abonnement

    Formulaire

    Un formulaire de recherche permet la saisie de critères facilitant l’accès aux composants stockés aux utilisateurs. Afin de pouvoir interagir avec ce type de formulaire, il est nécessaire de s’abonner à son ouverture :

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

    Note : Dans le cas d’un formulaire depuis l’écran de recherche, la variable id correspond à l’identifiant de son template.
    Dans le cas d’un formulaire de recherche depuis un dossier virtuel, la variable id correspond à l’identifiant de ce dossier virtuel.

    Critères

    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) {
    		console.log("Criterion " + criterion.getName() + " values changed to " + criterion.getValues());
    });
    

    Note : 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 pour interagir avec les critères sont disponibles dans la partie suivante.

    Actions

    Un formulaire de recherche dispose de deux conteneurs d’actions disponibles 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, id) {
    	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);
    });
    

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

    Note : Dans cette partie, la variable reasonedAnswerId permet d’utiliser l’identifiant de 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().

    Document en tant que pièce jointe sans indexation

    Il est possible d’utiliser l’ancien mode de création de document en tant que pièce jointe sans formulaire d’indexation en définissant une stratégie d’activation du mode Legacy.

    Dans l’exemple suivant, les pièces jointes ayant pour identifiant Appendices utilisent l’ancien mode, les autres le nouveau.

    LegacyDocumentAttachmentCreationStrategy.registerStrategy(function(task,attachment){
    	if("Appendices" == attachment.getId()){ 
    		return true;
    	}
        return false;
    });
    

    Résumé

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

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

    Exemple : 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();
    	}
    });