Visual Studio Code is an extensible code editor developed by Microsoft. It is cross-platform and compatible with Windows operating systems (7, 8 and 10), Linux (Debian, Ubuntu, Red Hat, Fedora, SUSE Ca) and macOS (10.10+).
The editor is open source, free and natively supports over a dozen languages (C, C++, C#, CSS, Dokerfile, Go, Groovy, HTML, JSON, Java, Javascript, Jenkinsfile, PHP, Perl, Python, Ruby, SQL, TypeScript, Visual Basic, XML, YAML, etc.).
The editor's open architecture authorizes the development of extensions to expand its features. These extensions (over 4700 of them) are available in a dedicated marketplace: https://marketplace.visualstudio.com/vscode.
Hardis provides its own extension to help with designing templates which can be used in APE.
Installing Visual Studio Code
The product is available for download on its main page: https://code.visualstudio.com/ or in this download area https://code.visualstudio.com/download.
In Windows, the installer is provided in an installation assistant-type executable file. The .NET prerequisites and installation details are available at this address: https://code.visualstudio.com/docs/setup/windows.
The tool includes an automatic update mechanism which enables one update per month to be downloaded.
For more information on how to use the editor, click on the links below (official documentation):
- Video tutorials: https://code.visualstudio.com/docs/getstarted/introvideos,
- Description of interface components: https://code.visualstudio.com/docs/getstarted/userinterface
Installing the APE Template Editing extension
It is available in the form of a .VSIX file in the %ADELIWS%Distrib\AdeliaPrintEngine directory. This extension requires a minimum version of Visual Studio Code 1.43.0.
The installation can be performed in two ways:
- Open a DOS command window and go to the directory where the extension is found: code --install-extension <extension_file_name.vsix>,
- Start Visual Studio Code (by double-clicking on the Visual Studio Code icon, via the Start menu, or in a command window by running the command below), then execute the "Install from VSIX..." command from the "Extensions" panel:
Features of the APE Template Editing extension
This extension provides a set of tools for improving APE template editing.
NB.: An APE template is a text file written in Apache FreeMarker language (click here for more details) using a set of external libraries provided by the APE.
The extension offers the following features:
Syntax highlighting for the content of a template: The editor is used to improve source code readability by highlighting the syntactic structures of the FreeMarker language (keywords, macro and function declarations, instructions and language constants) as well as the macros and functions of external libraries comprising the APE.
Code snippets: Ready-to-use source code fragments can be rapidly inserted without having to enter them in their entirety. It is therefore very easy to add a Freemarker <#if condition> <#else/> </#if> conditional instruction or a <@hardisFo.foFlow flowName=""> </@hardisFo.foFlow> tag,
Contextual help: The editor offers the option of displaying brief help on the elements (macros, functions, parameters) proposed through auto-complete when entering data and more detailed help (in the form of a tooltip) when hovering the mouse over these elements,
- Source code formatting: APE template formatting can be triggered to improve its readability. Code indentation rules are applied to the whole document,
- Auto-complete: When writing code, the editor supplies various options according to the current context, making it quicker to input the code. This help improves input of elements of external libraries provided by the APE as well as the constituent elements of the data model defined by the user and handled by the template.
Creating an APE template file
The extension features are automatically enabled when the Visual Studio Code editor detects the editing of a file with the .ftlx (main template file) or .ftl (module file or template fragment) extension.
There are two ways of creating a new APE template:
Via the "Explorer" panel by creating a named file in a project directory:
Or via the menu bar by creating a new unnamed file and associating the "FreeMarker for APE" programming language with it via the status bar:
Configuring the APE Template Editing extension
Access the parameters via the "Extensions" panel:
Locale Hover Help
This parameter changes the contextual help display language: By default, the language used is the Visual Studio Code editor user interface language which is English by default (en locale). To change the language to French (fr locale), select 'fr' in the combo box.
Only English and French are supported for the contextual help.
Note: the APE Template Editing extension supports English and French. The language used by the extension is the Visual Studio Code editor user interface language.
End-with-newline format
Insert a line break at the end of the document. The 'inherited' value is based on the 'html.format.endWithNewline' global property defined in the Visual Studio Code settings.
Extra-lines format
List of tabs, separated by commas, which must have a new extra line in front of them. For example, to add a line break before the hardisFo.foPageSequence tag when formatting, add the text "@hardisFo.foPageSequence" in the associated entry field. To add a line break before the hardisFo.foRoot end tag, add the text "/@hardisFo.foRoot".
Indent-size format
Number of space characters used for indentation. This property is only used if the indent-with-tabs format property is false (i.e. the indentation character is not the tabulation character). The 'inherited' value is based on the 'editor.tabSize' global property defined in the Visual Studio Code settings. ↑ Top of page
Indent-with-tabs format
Indentation using the tabulation character. If this property is True (by analysis or forced), the indent-size format property is not taken into account. The 'inherited' value is based on the value of the 'editor.detectIndentation' global property defined in the Visual Studio Code settings.
Max-preserve-newlines format
Maximum number of line breaks to preserve in a single block. The 'inherited' value is based on the 'html.format.maxPreserveNewLines' global property value defined in the Visual Studio Code parameters.
Preserve-newlines format
Preserves existing line breaks.
Unformatted format
List of tags, separated by commas, which must not be reformatted (tags themselves and their content).
In an APE template, to display text when executing while preserving its layout (line break, series of spaces or tabs), use the whiteSpace attribute.
Example:
<@hardisFo.foBlock whiteSpace="pre"> Do not collapse white spaces and tabs and preserve linefeed. </@hardisFo.foBlock>
The text will be formatted. There are two solutions to prevent this:
Solution 1: Encapsulate the text in a CDATA tag
<@hardisFo.foBlock whiteSpace="pre"> <![CDATA[ Do not collapse white spaces and tabs and preserve linefeed. ]]> </@hardisFo.foBlock>
Solution 2: Create a FreeMarker macro which encapsulates the call to the hardisFo.foBlock tag with the whiteSpace attribute and add the name of this macro (with the '@' character) to the list of tags to avoid formatting.
<#-- Declare macro --> <#macro unformatBlockText> <@hardisFo.foBlock whiteSpace="pre"> <#nested /> </@hardisFo.foBlock> </#macro> ... <#-- Macro call --> <@unformatBlockText> Do not collapse white spaces and tabs and preserve linefeed. </@unformatBlockText>
Wrap-attributes format
Specifies the format of tag attributes. The 'inherited' value is based on the 'html.format.wrapAttributes' global property value defined in the Visual Studio Code settings.
Wrap-line-length format
Maximum number of characters per line. The 'inherited' value is based on the 'html.format.wrapLineLength' global property value defined in the Visual Studio Code settings. Value 0 disables this limit.
Changing the Visual Studio Code interface language
Several languages are available for the interface. The translations are available in the dedicated marketplace. To install the Visual Studio Code French interface, select the "Configure Display Language" command from the command palette (Ctrl + Shift + P in Windows):
