Développement d'un composant

Un composant est un objet graphique intégrable dans un écran de YellowBox. Il permet de récupérer des informations de Yellowbox, depuis le contexte d’appel, de réaliser des traitements de tout type et d’afficher au format HTML un rendu. Il est possible de créer des interactions utilisateurs afin d’effectuer de nouveau traitements et de renvoyer du HTML.

L’intégration dans YellowBox d’un composant se fait directement à travers le mode éditeur en le sélectionnant et le positionnant à l’endroit souhaité.

Avant de créer le composant, il est nécessaire de préparer l’environnement en créant 4 sous dossiers dans le dossier “assets” pour centraliser l’ensemble des fichiers relatifs à votre objet HTML. Ces 4 dossiers sont les suivants : “css”, “html”, “js” et “img”.

Création de la classe principale

Pour créer un composant, il est nécessaire de créer une classe qui étend de la classe com.yellowbox.plugin.v3.Component.
Pour ce faire, il faut cliquer droit sur le projet puis “New” -> “Class”.
Saisir un nom de package, par exemple com.dimosoftware.example.components.
Saisir un nom pour la classe, par exemple “ExampleComponent”. Dans la zone Superclass, cliquer sur le bouton “Browse” et entrer “Component” puis sélectionner la classe com.yellowbox.plugin.v3.Component, cliquer sur le bouton “OK” puis “Finish”.

Méthode getParams()

Cette méthode permet de définir les paramètres d’entrée nécessaires au traitement. Dans les composants, aucun paramètre de sortie ne sera traité.

Les paramètres se définissent comme pour la fonction (voir ici).

Méthode getHtml()

Il s’agit de la méthode principale qui effectue les traitements souhaités et retourne un String contenant le code HTML de l’objet que l’on souhaite afficher dans YellowBox.
Cette méthode est détaillée dans les exemples, il est possible d’écrire le code HTML dans un fichier ou directement de retourner un String dans la méthode.

Méthode getListCss()

Cette méthode permet de référencer dans une liste l’ensemble des fichiers CSS nécessaires pour présenter le composant.
Il est possible d’y définir des liens vers des fichiers CSS présents sur un CDN ou en local dans le dossier “css” :

List<String> listCss = new ArrayList<>();
listCss.add("https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.0.0/css/bootstrap.css");
listCss.add("css/pure.css");

Méthode getListJs()

Cette méthode permet de référencer dans une liste l’ensemble des fichiers Javascript nécessaires pour présenter le composant.
Il est possible d’y définir des liens vers des fichiers Javascript présents sur un CDN ou en local dans le dossier “js” :

List<String> listJs = new ArrayList<>();
listJs.add("https://cdn.datatables.net/1.10.16/js/dataTables.bootstrap4.min.js");
listJs.add("js/pure.js");

Depuis un fichier javascript, il est possible d’appeler les fonctions suivantes :

openRecord(idRecord, inNewOnglet) : qui permet d’ouvrir un record (une fiche) dans un nouvel onglet spécifié par le second paramètre booleen
createRecord(idTable) : qui permet d’ouvrir la fiche de création d’un enregistrement en passant l’id de la table concernée

Méthode getAssets()

Cette méthode permet de référencer dans une liste l’ensemble des fichiers nécessaires pour présenter le composant, comme des images par exemple.

List<String> listImg = new ArrayList<>();
listImg.add("img/example.png");

Méthode getServlets()

Cette méthode permet de référencer l’ensemble des classes servlets implémentées dans le code source.

Une servlet correspond à une interaction utilisateur avec le composant nécessitant un traitement côté serveur.

public List<Class<? extends Servlet>> getServlets() { 
    List<Class<? extends Servlet>> listServlet = new ArrayList<>();
    listServlet.add(Example1Servlet.class);
    listServlet.add(Example2Servlet.class);
    return listServlet;
}

Création d’une servlet

Afin de structurer le code source, il est conseillé de centraliser le ou les servlets dans un package spécifique, nommé “servlets”.
Pour créer une servlet, il faut cliquer droit sur le projet puis “New” -> “Class”. Saisir un nom de package, par exemple com.dimosoftware.example.servlets.
Saisir un nom pour la classe, par exemple “ExampleServlet”. Dans la zone Superclass, cliquer sur le bouton “Browse” et entrer “Servlet” puis sélectionner la classe com.yellowbox.plugin.v3.Servlet, cliquer sur le bouton “OK” puis “Finish”.

La classe générée se compose de deux méthodes à implémenter.

Méthode getTitle()

Il s’agit ici de fournir la traduction du composant, telle qu’elle sera présentée lors de la sélection du composant, en instanciation du plugin dans YellowBox.
Si la méthode n’est pas implémentée, la méthode getName() sera utilisée à la place.

Méthode getName()

Il s’agit ici de fournir le nom du composant sans espace ni caractères spéciaux qui sera utilisé comme ID du composant.
Cette méthode permet de définir le nom (String) qui sera utilisé en Javascript pour exécuter cette servlet. L’appel sera le suivant :

callServlet(nomServlet)

Méthode call()

Cette méthode correspond à la méthode de traitement de la servlet.

Elle prend en paramètre un objet ParamValues, représentant un ensemble de paramètres nom/valeur fournis lors de l’appel de cette servlet. Ces ParamValue seront assimilés aux paramètres de request.

Voici un exemple de récupération d’un paramètre :

String paramExample1 = paramsServlet.getStringValue("param1");

Cette méthode retourne un string correspondant aux données qui seront renvoyées au client suite à l’appel.
Il existe différentes méthodes en fonction du type de donnée à récupérer :

getStringValue(String) : String
getIntValue(String) : int
getFloatValue(String) : float
getBoolValue(String) : boolean
getIdFieldValue(String) : String
getIdMultiSelectoValue(String) : String
getIdTableValue(String) : String
getIdRechercheValue(String) : String
getDateValue(String) : Date
getColorValue(String) : String
getFileValue(String) : byte[]
getPhoneNumberValue(String) : String
getLongTextrValue(String) : String

Il peut s’agir de code HTML ou de JSON ou tout autre format de données.

Appel de la servlet côté client

Afin de traiter l’interaction entre l’utilisateur et la servlet, une méthode Javascript est disponible, nommée callServlet, et s’utilise comme suit :

callServlet("exampleServlet",{"param1":"valduparam"},function(data) { 
    data = JSON.parse(data); 
    }, 
    function(error) { 
        alert("Error : " + error.message); 
    }
);

Le premier paramètre correspond au nom de la servlet a appeler, le deuxième correspond à un objet javascript comprenant les paramètres clé valeur, le troisième correspond au callback lors du success de la fonction et le dernier au callback d’erreur.
Pour envoyer des fichiers via une servlet il faut utiliser la méthode callServletFile :

var formData = new FormData();
formData.append('file',file);
callServletFile('ServletFichier', formData, function(data) {
                //do what you want with data
                var json = JSON.parse(data);
            },
            function(error) {
                // handle error
                console.log("Error",error);
            });

Le 1er paramètre est le nom de la servlet à appeler, le second correspond à un objet FormData javascript (cf FormData() MDN), les deux autres paramètres sont identiques à la méthode callServlet.
Pour récupérer ce paramètre côté Servlet, il faudra utiliser la méthode getFileValue(file) qui retournera un tableau de byte.
Le FormData peut avoir plusieurs fichiers en spécifiant des clés uniques, par exemple :

var formData = new FormData();
formData.append('file',file);
formData.append('file2',file2);

Lorsqu’on utilise la servlet callServletFile, pour passer des paramètres supplémentaires à la servlet qui ne sont pas des fichiers, il faut les ajouter au FormData de la même manière qu’un fichier :

var formData = new FormData();
var param = "myParam";
formData.append('file',file);
formData.append('myParam',myParam);

Pour le récupérer côté Servlet, il faut utiliser la méthode getStringValue("myParam").
Un exemple d’utilisation de cette servlet est présent dans les exemples.

Accès à l’instance du composant

Il est possible d’accéder à l’instance du composant pour en récupérer des propriétés en utilisant la commande :

ExampleComponent exampleComponent = (ExampleComponent)getComponent();

Intégration de l’Oauth2

Pour créer un plugin qui utilise une authentification de type oauth2 pour intégrer les services d’un fournisseur tiers, Yellowbox intègre un module de gestion de ce type d’authentification.

Lors de la création d’un composant ou d’une fonction qui propose d’exploiter l’oauth2, créer un constructeur avec

	setOauth2(true);

Dès lors le paramétrage fera apparaître les paramètres nécessaires à l’authentification oauth2 :

tokenName - un nom pour ce token
grantType - le type d’authentification qui dépend du serveur tiers, par exemple authorization_code pour utiliser les service de webmecanik
redirectUri - http://localhost:8080/prod/callbackoauth2 pour yellowbox
authorizationUri - l’adresse du serveur d’authentification mise à disposition par le tiers
accesTokenUri - l’adresse du serveur de token mise à disposition par le tiers
clientId - paramètre d’authentification auprès du tiers
clientSecret - paramètre d’authentification auprès du tiers

Lors du clic sur connexion, Un appel est passé au serveur tiers d’authentification qui fera basculer sur un nouvel onglet de saisie des login et mot de passe. Ces informations seront ensuite traitées par le serveur tiers pour fournir un code d’authentification sur une adresse de callback mise à disposition par yellowbox. Après un nouvel appel pris en charge par yellowbox, le serveur tiers fournit un ensemble d’informations d’authentification dont un access token qui pourra être utilisé pour s’authentifier auprès de ce tiers pour utiliser ses services.

Lorsque la connexion à été authentifiée par le tiers, le témoin d’authentification dans le paramétrage indique ‘connecté’. Le paramétrage fait également apparaître l’access token et le refresh token obtenus en réponse du processus d’authentification.

Dans le plugin, l’access token est rendu disponible par la méthode

    getAccesToken()

Cette méthode est disponible dans la méthode getParams() si on utilise l’interface par défaut. Elle est disponible également dans la méthode getParamInstanceUI() qui permet d’utiliser une interface personnalisée. Elle est enfin disponible dans le corps du composant par le biais de la méthode getHtml() ou dans une fonction, dans le call().

L’access token ayant une durée de vie limitée, le serveur d’authentification fournit également un refresh token et une durée de validité. Yellowbox se chargera de toujours fournir un access token valide lors de l’appel à getAccesToken(). Si le token disponible n’est plus valide, une procédure de rafraîchissement du token sera suivie par yellowbox pour récupérer un nouvel access token valide. Si la date de validité du refresh token est également dépassée, une action humaine sera nécessaire puisque la saisie du couple login / mot de passe sera indispensable. Un message invitera l’utilisateur à contacter son administrateur pour procéder à nouveau à la démarche d’authentification dans le paramétrage du plugin.

Développement d'un composant

Création de la classe principale #

Méthode getParams() #

Méthode getParamInstanceUI() #

Méthode getName() #

Méthode getDescription() #

Méthode getHtml() #

Méthode getListCss() #

Méthode getListJs() #

Méthode getAssets() #

Méthode getServlets() #

Création d’une servlet #

Méthode getTitle() #

Méthode getName() #

Méthode call() #

Appel de la servlet côté client #

Accès à l’instance du composant #

Intégration de l’Oauth2 #

Création de la classe principale

Méthode getParams()

Méthode getParamInstanceUI()

Méthode getName()

Méthode getDescription()

Méthode getHtml()

Méthode getListCss()

Méthode getListJs()

Méthode getAssets()

Méthode getServlets()

Création d’une servlet

Méthode getTitle()

Méthode getName()

Méthode call()

Appel de la servlet côté client

Accès à l’instance du composant

Intégration de l’Oauth2