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