L'auto-complétion est un procédé qui consiste à proposer, lors de la frappe au clavier par l'utilisateur, un complément de saisie : on parle de saisie intuitive.

L'auto-complétion fait partie, au sein de Visual Studio Code d'un ensemble plus général nommé IntelliSense qui regroupe un ensemble de fonctionnalités conçues pour faciliter le codage (comme la coloration syntaxique, le reporting d'erreur, l'aide sur les paramètres, l'affichage d'aide ou d'info express sur un élément, etc).

Aide à la saisie des instructions FreeMarker

Rappel : Le moteur APE s'appuie sur le framework Apache FreeMarker en version 2.3.28. De même, l'extension APE Template Editing se base sur cette version du langage.

L'extension propose, pour le langage FreeMarker, une aide à la saisie des balises (les directives) et des fonctions intégrées (les built-ins).

Contrairement aux snippets FreeMarker qui permettent d'insérer un fragment de code code complet (c'est-à-dire une balise), l'aide à la saisie permet de compléter rapidement l'encours de saisie en proposant des suggestions liées au contexte.

Les directives FreeMarker

Ce sont les instructions, écrites sous la forme de balises, qui constituent le corps du langage.

Le déclenchement de l'aide à la saisie de directives se produit après la saisie des deux premiers caractères d'ouverture de balise "<#" : Une liste de suggestions s'affiche et son contenu s'affine au fur et à mesure de la saisie. Comme pour les snippets, la navigation dans la liste se fait avec les touches "Flèche Haut" et "Flèche Bas" et la sélection avec la touche "Entrée" ou "Tabulation".

Lorsque la directive est sans paramètres, elle s'insère dans le document et le curseur se retrouve à la fin du code inséré.

Lorsque la directive a un ou plusieurs paramètres, le curseur se positionne sur le premier paramètre : l'utilisateur doit modifier la valeur du paramètre et passer au paramètre suivant via la touche "Tabulation".

De même, lorsqu'une directive est une balise non vide, une aide à la saisie est proposée après la saisie des trois premiers caractères de fermeture de balise "</#" :

Les built-ins FreeMarker

Ce sont les fonctions intégrées du langage.

Le déclenchement de l'aide à la saisie des built-ins se produit après la saisie du caractère d'appel "?" : Une liste de suggestions s'affiche et son contenu s'affine au fur et à mesure de la saisie. Comme pour les snippets, la navigation dans la liste se fait avec les touches "Flèche Haut" et "Flèche Bas" et la sélection avec la touche "Entrée" ou "Tabulation".

Lorsque la built-in est sans paramètres, elle s'insère dans le document et le curseur se retrouve à la fin du code inséré.

Lorsque la built-in a un ou plusieurs paramètres, le curseur se positionne à l'intérieur des parenthèses d'appel de la fonction : l'utilisateur doit saisir ses propres valeurs de paramètres.

Aide à la saisie des directives des bibliothèques externes

L'extension propose l'auto-complétion dans l'écriture de l'appel aux macros et fonctions définies dans les bibliothèques Core, CSS, FO et Adv.

Contrairement aux snippets des bibliothèques externes qui permettent d'insérer un fragment de code complet (c'est-à-dire l'appel à une macro ou fonction), l'aide à la saisie permet de compléter rapidement l'encours de saisie en proposant des suggestions liées au contexte.

La saisie de l'identifiant d'une entité (macro ou fonction) s'effectue en trois étapes :

1. Saisie de l'espace de nom (le namespace de la bibliothèque externe utilisée),
2. Saisie du caractère "." (appel d'une entité définie dans le namespace précédemment saisi),
3. Saisie du nom de l'entité.

L'auto-complétion apporte une aide à la saisie des étapes 1 et 3.

Macro des bibliothèques externes

Le déclenchement de l'aide à la saisie pour l'étape 1 se produit après la saisie des deux premiers caractères d'ouverture de balise d'appel d'une macro "<@" : Une liste de suggestions s'affiche avec l'ensemble des namespaces des bibliothèques externes et son contenu s'affine au fur et à mesure de la saisie. Comme pour les snippets, la navigation dans la liste se fait avec les touches "Flèche Haut" et "Flèche Bas" et la sélection avec la touche "Entrée", "Tabulation" ou ".". La différence de comportement est décrit comme suit :

• la sélection d'un namespace via "Entrée" ou "Tabulation" provoque l'insertion du namespace dans le document; l'utilisateur peut poursuivre sa saisie par l'étape 2 (saisie du caractère "."). L'étape 2 provoque l'affichage d'une liste de suggestions (étape 3) contenant l'ensemble des noms de macros définies dans la bibliothèque externe du namespace sélectionné et son contenu s'affine au fur et à mesure de la saisie. Comme pour les snippets, la navigation dans la liste s'effectue avec les touches "Flèche Haut" et "Flèche Bas" et la sélection avec la touche "Entrée", "Tabulation" ;
• la sélection d'un namespace via "." provoque l'insertion du namespace suivi du caractère "." dans le document et déclenche automatiquement la liste de suggestion de l'étape 3.

Lorsque la macro sélectionnée admet un ou plusieurs paramètres obligatoires, alors ceux-ci sont automatiquement insérés dans l'appel de la macro : l'utilisateur doit saisir la valeur de chaque paramètre. Le passage d'un paramètre au suivant se fait par la touche "Tabulation".

Lorsque la macro sélectionnée est une directive vide, alors l'appel complet de la macro est insérée. A contrario, lorsque la directive n'est pas vide, alors seule la balise de début d'appel de la macro est insérée : l'insertion de la balise de fin doit se faire par saisie, l'auto-complétion permettant de saisir rapidement son contenu.

Paramètres des macros des bibliothèques externes

L'auto-complétion est aussi présente dans la saisie des paramètres d'une macro. Pour cela, il suffit de placer le curseur à l'intérieur de la balise ouvrante de la macro (un caractère "espace" doit précéder le curseur) et d'appuyer sur les touches "Ctrl" + "Espace" : Une liste de suggestions s'affiche avec l'ensemble des paramètres de la macro et son contenu s'affine au fur et à mesure de la saisie. Comme pour les snippets, la navigation dans la liste se fait avec les touches "Flèche Haut" et "Flèche Bas" et la sélection avec la touche "Entrée", "Tabulation".

Lorsqu'un paramètre est sélectionné et s'il admet comme valeur des valeurs prédéfinies, une liste de suggestions s'affiche comme aide à la saisie de sa valeur.

Fonctions des bibliothèques externes

L'aide à la saisie des fonctions des bibliothèques externes se fait en suivant les mêmes étapes que pour les macros. L'appel d'une fonction doit se faire à l'intérieur d'une interpolation (l'expression ${...}) ou comme une valeur de paramètre de macro ou directive FreeMarker.

Aide à la saisie du data model d'un template

Un template APE manipule et affiche des données transmises sous la forme d'un data model (modèle de données). Il est possible d'activer une aide à la saisie lors de l'accès au modèle arborescent du data model : l'auto-complétion propose l'accès aux sous-variables lors de l'utilisation de la notation "point" (déclenché par la saisie du caractère ".").

Cette fonctionnalité nécessite un fichier de description du data model (fichier au format JSON) : Par conversion, ce fichier est lié à un template APE et a pour nom <template_name>_dmodel.json où <template_name> est le nom (sans l'extension .flt ou .ftlx) du fichier template APE associé.

Format du fichier data model

Ce fichier est un fichier au format JSON. Seule la structuration de cette donnée JSON est utilisée par l'aide à la saisie ; les valeurs de type simple (renseignées obligatoirement de façon à fournir une donnée JSON valide syntaxiquement) ne sont pas prises en compte.

La structure JSON est identique à celle de l'attribut jsonDataModel lors de l'appel au service Web mergeDoc de l'APE : Il s'agit d'un objet JSON dont les attributs sont les données du data model. Un attribut peut avoir un type JSON simple (String, Number, Boolean) ou complexe (Objet ou Tableau).

Cette donnée JSON est donc "l'image" du contenu de l'attribut jsonDataModel lors d'un cas réel d'utilisation du service Web mergeDoc avec quelques différences et limitations :

• Une donnée optionnelle dans le data model (c'est-à-dire une donnée associée à un attribut qui, suivant les cas réels d'utilisation, n'est pas présente dans le data model) devra apparaître dans la donnée JSON si l'on veut qu'elle soit proposée par l'aide à la saisie,
• Une donnée de type Tableau peut se limiter à un seul élément pour simplifier la structure : Lors de l'analyse structurelle d'une donnée Tableau, seul le premier élément du tableau est pris en compte. L'aide à la saisie détecte l'utilisation de la syntaxe d'accès à un élément d'une donnée Tableau (via la notation [ ... ]) mais n'analyse pas la valeur de l'index du tableau (pour l'auto-complétion, il n'y a pas de différence sémantique entre les instructions suivantes : .data_model.myArray[0] , .data_model.myArray[10] et .data_model.myArray[myIndex]),
• La conséquence du point précédent est qu'une donnée de type Tableau doit avoir des données homogènes : L'analyse se faisant sur le premier élément, l'aide à la saisie suppose donc que tous les éléments du tableau sont du même type.

Saisie du data model

L'accès au data model dans un template APE se fait en utilisant la variable prédéfinie .data_model : Elle représente la racine du data model. C'est un objet de type Hash (un tableau associatif) représentant le contenu de l'attribut jsonDataModel lors d'un cas réel d'utilisation du template.

Lors de l'utilisation de l'aide à la saisie durant la phase de développement du template, la variable .data_model représente le contenu de la donnée JSON du fichier de description du data model.

Il est possible de développer en parallèle le fichier de description du data model et le template dans l'éditeur Visual Studio Code : Le chargement et l'analyse du fichier data model est déclenché à chaque fois qu'un éditeur contenant un document template APE devient l'éditeur actif (l'onglet actif).

Cependant, si le fichier de description du data model est modifié avec un autre éditeur de texte (donc sans avoir besoin de changer l'onglet actif dans Visual Studio Code), alors il est possible de commander le (re)chargement du fichier via une commande de l'extension. Pour cela, il faut ouvrir la palette de commandes avec le raccourci-clavier (sous Windows) "Ctrl" + "Maj" + "P", puis taper la commande "APE Template Editing : Load data model file" pour la sélectionner et appuyer sur la touche "Entrée" pour l'activer.

Dans le document template APE, le déclenchement de l'aide à la saisie du data model se produit après la saisie du caractère "." près la chaîne ".data_model" : Une liste de suggestions contenant les attributs de niveau racine s'affiche et son contenu s'affine au fur et à mesure de la saisie. Comme pour les snippets, la navigation dans la liste se fait avec les touches "Flèche Haut" et "Flèche Bas" et la sélection avec la touche "Entrée", "Tabulation" ou ".".

Une fois qu'un attribut est sélectionné, s'il est de type complexe, alors il est possible de déclencher l'aide à la saisie des attributs le constituant (si cet attribut est de type Objet ou Tableau d'objet) en saisissant le caractère "." ou de manière automatique s'il a été précédemment sélectionné avec la touche "." (sous réserve qu'il soit de type Objet).