Visual Studio Code est un éditeur de code extensible développé par Microsoft. Cet outil est multiplateforme et compatible avec les systèmes d'exploitation Windows (7, 8 et 10), Linux (Debian, Ubuntu, Red Hat, Fedora, SUSE Ca) et macOS (10.10+).
Cet éditeur est open source et gratuit, supportant nativement plus d'une dizaine de langages (C, C++, C#, CSS, Dokerfile, Go, Groovy, HTML, JSON, Java, Javascript, Jenkinsfile, PHP, Perl, Python, Ruby, SQL, TypeScript, Visual Basic, XML, YAML, etc.).
L'architecture ouverte de l'éditeur autorise le développement d'extensions permettant d'étendre ses fonctionnalités. Ces extensions sont regroupées au sein d'une place de marché dédiée (plus de 4700 extensions disponibles), accessible à cette adresse : https://marketplace.visualstudio.com/vscode.
Hardis fournit sa propre extension pour l'aide à la conception de templates utilisables dans l'APE.
Installation de Visual Studio Code
Ce produit est disponible au téléchargement sur sa page principale : https://code.visualstudio.com/ ou sur cet espace de téléchargement https://code.visualstudio.com/download.
Sous Windows, l'installeur est fourni sous la forme d'un fichier exécutable de type assistant d'installation. Les prérequis .NET et les détails de l'installation sont disponibles à cette adresse : https://code.visualstudio.com/docs/setup/windows.
L'outil intègre un mécanisme de mise à jour automatique qui permet de télécharger une mise à jour par mois.
Pour plus d'informations sur la prise en main de cet éditeur, cliquez sur les liens ci-dessous (documentation officielle) :
- Vidéos tutorielles : https://code.visualstudio.com/docs/getstarted/introvideos,
- Description des composants de l'interface : https://code.visualstudio.com/docs/getstarted/userinterface
Installation de l'extension APE Template Editing
Elle est disponible sous la forme d'un fichier .VSIX situé dans le répertoire %ADELIWS%Distrib\AdeliaPrintEngine. Cette extension requiert une version minimale de Visual Studio Code 1.43.0.
L'installation peut s'effectuer de deux façons :
- Ouvrir une fenêtre de commande DOS et se placer dans le répertoire où se trouve l'extension, puis lancer la commande suivante: code --install-extension <nom_fichier_extension.vsix>,
- Lancer Visual Studio Code (soit en double-cliquant sur l'icone Visual Studio Code, soit via le menu Démarrer, soit dans une fenêtre de commande en lançant la commande ci-dessus), puis exécuter la commande "Install from VSIX..." à partir du panel "Extensions" :
Les fonctionnalités de l'extension APE Template Editing
Cette extension fournit un ensemble d'outils améliorant l'édition de template APE.
Rappel : Un template APE est un fichier textuel écrit dans le langage Apache FreeMarker (cliquez ici pour plus de détails) en s'appuyant sur un ensemble de bibliothèques externes fournies par l'APE.
L'extension offre les fonctionnalités suivantes :
Coloration syntaxique du contenu d'un template : L'éditeur permet d'améliorer la lisibilité du code source en mettant en évidence les structures syntaxiques du langage FreeMarker (mots clés, déclaration de macros et fonctions, instructions et constantes du langage) ainsi que les macros et fonctions des bibliothèques externes constitutives de l'APE,
Snippets de code : Il est possible d'insérer rapidement des fragments de code source prêts à l'emploi sans devoir en saisir l'intégralité. Il est alors très facile d'ajouter une instruction conditionnelle Freemarker <#if condition> <#else/> </#if> ou une balise <@hardisFo.foFlow flowName=""> </@hardisFo.foFlow>,
Aide contextuelle : L'éditeur offre la possibilité d'afficher une aide succincte sur les éléments (macros, fonctions, paramètres) proposés lors de l'auto-complétion à la saisie et une aide plus détaillée (sous la forme d'une info-bulle) lors du survol à la souris de ces mêmes éléments,
Formatage de code source : Il est possible de déclencher le formatage d'un template APE afin d'améliorer sa lisibilité. Des règles d'indentation de code sont appliquées à l'ensemble du document,
- Auto-complétion : Lors de l'écriture de code, l'éditeur fournit un certain nombre de propositions en fonction du contexte courant, ce qui permet d'accélérer la saisie du code. Cette assistance permet d'améliorer la saisie des éléments des bibliothèques externes fournies par l'APE ainsi que des éléments constitutifs du data model défini par l'utilisateur et manipulé par le template.
Création d'un fichier template APE
L'activation des fonctionnalités de l'extension se fait automatiquement lorsque l'éditeur Visual Studio Code détecte l'édition d'un fichier avec l'extension .ftlx (fichier de template principal) ou .ftl (fichier de module ou fragment de template).
La création d'un nouveau template APE peut s'effectuer de deux façons :
Soit via le panel "Explorer" en créant un fichier nommé dans un répertoire du projet :
Soit via la barre de menu en créant un nouveau fichier sans nom et en lui associant le langage de programmation "FreeMarker for APE" par la barre de statut :
Paramétrage de l'extension APE Template Editing
L'accès au paramétrage se fait via le panel "Extensions" :
Hover Help Locale
Ce paramètre permet de changer la langue d'affichage de l'aide contextuelle : Par défaut, la langue utilisée est celle de l'interface utilisateur de l'éditeur Visual Studio Code qui est par défaut l'Anglais (locale en). Pour changer la langue en Français (locale fr), sélectionner 'fr' dans la liste déroulante.
Seules les langues anglaise et française sont supportées pour l'aide contextuelle.
Remarque : l'extension APE Template Editing supporte les langues anglaise et française. La langue utilisée par l'extension est celle de l'interface utilisateur de l'éditeur Visual Studio Code.
Format End-with-newline
Insère à la fin du document un saut de ligne. La valeur 'inherited' se base sur la valeur de la propriété globale 'html.format.endWithNewline' définie dans les paramètres de Visual Studio Code.
Format Extra-liners
Liste des balises, séparées par des virgules, qui devraient avoir une nouvelle ligne supplémentaire devant elles. Par exemple, pour ajouter lors du formatage un saut de ligne avant la balise hardisFo.foPageSequence, il faut ajouter le texte "@hardisFo.foPageSequence" dans le champ de saisie associé. Pour ajouter un saut de ligne avant la balise de fin hardisFo.foRoot, il faut ajouter le texte "/@hardisFo.foRoot ".
Format Indent-size
Nombre de caractères espace utilisés pour l'indentation. Cette propriété est prise en compte seulement si la propriété Format indent-with-tabs est à faux (c'est-à-dire que le caractère d'indentation n'est pas le caractère tabulation). La valeur 'inherited' se base sur la valeur de la propriété globale 'editor.tabSize' définie dans les paramètres de Visual Studio Code.
Format Indent-with-tabs
Indentation en utilisant le caractère tabulation. Si cette propriété est à Vrai (par analyse ou forcée) alors la propriété Format indent-size n'est pas prise en compte. La valeur 'inherited' se base sur la valeur de la propriété globale 'editor.detectIndentation' définie dans les paramètres de Visual Studio Code.
Format Max-preserve-newlines
Nombre maximal de sauts de ligne à conserver en un seul bloc. La valeur 'inherited' se base sur la valeur de la propriété globale 'html.format.maxPreserveNewLines' définie dans les paramètres de Visual Studio Code.
Format Preserve-newlines
Conserve les sauts de lignes existants.
Format Unformatted
Liste des balises, séparées par des virgules, qui ne doivent pas être reformatées (balises elles-mêmes et leur contenu).
Dans un template APE, pour afficher à l'exécution du texte en préservant sa mise en page (saut de ligne, suite d'espaces ou de tabulations), il faut utiliser l'attribut whiteSpace.
Exemple :
<@hardisFo.foBlock whiteSpace="pre"> Do not collape white spaces and tabs and preserve linefeed. </@hardisFo.foBlock>
Lors du formatage, le texte sera mis en forme. Pour éviter cela, il existe deux solutions :
Solution 1 : Encapsuler le texte dans une balise CDATA
<@hardisFo.foBlock whiteSpace="pre"> <![CDATA[ Do not collape white spaces and tabs and preserve linefeed. ]]> </@hardisFo.foBlock>
Solution 2 : Créer une macro FreeMarker qui encapsule l'appel à la balise hardisFo.foBlock avec l'attribut whiteSpace et ajouter le nom de cette macro (avec le caractère '@') à la liste des balises à ne pas formater.
<#-- Declare macro --> <#macro unformatBlockText> <@hardisFo.foBlock whiteSpace="pre"> <#nested /> </@hardisFo.foBlock> </#macro> ... <#-- Macro call --> <@unformatBlockText> Do not collape white spaces and tabs and preserve linefeed. </@unformatBlockText>
Format Wrap-attributes
Indique la mise en forme des attributs des balises. La valeur 'inherited' se base sur la valeur de la propriété globale 'html.format.wrapAttributes' définie dans les paramètres de Visual Studio Code .
Format Wrap-line-length
Nombre maximum de caractères par ligne. La valeur 'inherited' se base sur la valeur de la propriété globale 'html.format.wrapLineLength' définie dans les paramètres de Visual Studio Code . La valeur 0 désactive cette limite.
Changement de langue de l'interface Visual Studio Code
Plusieurs langues sont disponibles pour l'interface. Ces traductions sont disponibles sur la place de marché dédiée. Pour installer l'interface française de Visual Studio Code, sélectionner la commande "Configure Display Language" à partir de la palette de commandes (Ctrl + Maj + P sous Windows) :
