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.51.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.
- Test and development: By integrating a REST client and a J2EE Sprint Boot application that sets out all the APE's Web services, you can define test cases for each template that you are currently developing that can be executed by one click. The resulting document is viewable directly in the Visual Studio Code editor.
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:
Play video in media player ↑ Top of page
Configuring the APE Template Editing extension
Access the parameters via the "Extensions" panel:
Ape Spring Boot Automatic Start App Executing Test Case
When executing a test case command, this option enables you to automatically start the Spring Boot APE if it has stopped.
Ape Spring Boot Java Path
Indicates a root folder for installing a Java JRE or JDK (earliest version 1.8) required to execute the embedded Spring Boot APE.
Ape Spring Boot Log Style Debug
Indicates in the Spring Boot APE output channel the text styles to apply to the DEBUG log.
Ape Spring Boot Log Style Error
Indicates in the Spring Boot APE output channel the text styles to apply to the ERROR log.
Ape Spring Boot Log Style Fatal
Indicates in the Spring Boot APE output channel the text styles to apply to the FATAL log.
Ape Spring Boot Log Style Header
Indicates in the Spring Boot APE output channel the text styles to apply to the header (log timestamp and PID of the Spring Boot APE process).
Ape Spring Boot Log Style Info
Indicates in the Spring Boot APE output channel the text styles to apply to the INFO log.
Ape Spring Boot Log Style Trace
Indicates in the Spring Boot APE output channel the text styles to apply to the TRACE log.
Ape Spring Boot Log Style Warn
Indicates in the Spring Boot APE output channel the text styles to apply to the WARN log.
Ape Spring Boot Waiting Time Before Executing Test Case
Indicates the wait time (in seconds) shown as a countdown, for starting of the Spring Boot APE to be completed. Depending on host machine performance, you may need to increase this time when this application starts automatically (Automatic Start App Executing Test Case option).
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.
Import Modules Xchart Namespace
You can use the Xchart module to design a template. This module is loaded with the aid of an inclusion directive to insert at the start of the template:
<#import "/lib_xchart.ftl" as xchartModule/>
Note: The "xchartModule" namespace name is provided as an example and can be replaced by a name of your choosing (in accordance with Apache Freemarker namespaces syntax).
To benefit from the design aids when using this module (code snippets, context-sensitive help, auto-completion) in the same way as the Core, CSS, FO and Adv libraries, in this field you must enter the value of the namespace name provided above (see the "xchartModule" example).
Pdf Preview Default Cursor
Indicates the default shape of the mouse cursor used in the PDF viewer when displaying the result document in Portable Document Format.
Pdf Preview Default Scale
Indicates the default scale used in the PDF viewer when displaying the result document in Portable Document Format.
Pdf Preview Default Scroll Mode
Indicates the default scrolling mode used in the PDF viewer to display the pages of the result document in Portable Document Format.
Pdf Preview Default Sidebar
Determines default visibility of the left sidebar in the PDF viewer when displaying the result document in Portable Document Format.
Pdf Preview Default Spread Mode
Determines the default mode for page spread (no double display or double pages, odd pages to the left or double pages, even pages to the left) in the PDF viewer when displaying the result document in Portable Document Format.
Pdf Preview User Interface Language
Determines the PDF viewer user interface language.
Test Case Result Preview Single Viewer Of The Test Case Result Document
Indicates the number of viewers used to display the test case execution result documents: A single viewer for all executed test cases, or one for each executed test case.
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):
