Auto-complete is a process which involves suggesting the rest of a word when the user is typing: it is known as intuitive input.
In Visual Studio Code, auto-complete is part of the broader IntelliSense which includes a set of features designed to make coding easier (like syntax highlighting, error reporting, parameter help, displaying help or quick info on an element, etc.).
Help with entering FreeMarker instructions
Remember: The APE is based on Apache FreeMarker version 2.3.28 framework. The APE Template Editing extension is also based on this language version.
The extension proposes, for the FreeMarker language, help with entering tags (directives) and integrated functions (built-ins).
Unlike FreeMarker snippets which are used to insert code fragments (i.e. a tag), input help makes input quicker by making context-related suggestions.
FreeMarker directives
These are instructions, written in the form of tags, which make up the language body.
Help with inputting directives is triggered after entering the first two tag opening characters "<#": A list of suggestions is displayed and its content is refined as more data is input. Like for snippets, the "Up arrow" and "Down arrow" are used to navigate through the list and "Enter" or "Tab" are used to select.
When the directive has no parameters, it is inserted into the document and the cursor is at the end of the inserted code.
When the directive has one or more parameters, the cursor is positioned on the first parameter: the user must change the parameter value and move to the next parameter with the "Tab" key.
When a directive is a non-empty tab, input help is proposed after entering the first three tag closing characters "</#":
FreeMarker built-ins
These are the built-in functions of the language.
Built-in input help is triggered after entering the call character "?": A list of suggestions is displayed and its content is refined as more data is input. Like for snippets, the "Up arrow" and "Down arrow" are used to navigate through the list and "Enter" or "Tab" are used to select.
When the built-in does not have any parameters, it is inserted into the document and the cursor is at the end of the inserted code.
When the built-in has one or more parameters, the cursor is inside the function call parentheses: the user must enter their own parameter values.
Help with entering external library directives
The extension proposes auto-complete when writing calls for macros and functions defined in the Core, CSS, FO and Adv libraries.
Unlike external library snippets which are used to insert a complete fragment of code (i.e. call to a macro or function), input help makes it quicker to complete the input by making context-related suggestions.
An entity (macro or function) identifier is entered in three steps:
- Enter the namespace (the namespace of the external library used),
- Enter the "." character (call from an entity defined in the previously entered namespace),
- Enter the entity name.
Auto-complete provides input help in steps 1 to 3.
External libraries macro
Input help for step 1 is triggered after entering the first two tag opening characters for calling a macro "<@": A list of suggestions is displayed with all the external library namespaces and its content is refined as more data is input. Like for snippets, the "Up arrow" and "Down arrow" are used to navigate through the list and "Enter", "Tab" and "." are used to select. The behavioral difference is described as follows:
- selecting a namespace via "Enter" or "Tab" inserts the namespace in the document. The user can continue inputting via step 2 (enter the "." character). Step 2 displays a list of suggestions (step 3) containing all the names of the macros defined in the external library of the selected namespace and its content is refined as more information is input. Like for snippets, the "Up arrow" and "Down arrow" are used to navigate through the list and "Enter" and "Tab" are used to select;
- selecting a namespace via "." inserts the namespace followed by the "." character into the document and automatically triggers the suggestion list in step 3.
When the selected macro admits one or more mandatory parameters, these are automatically inserted into the macro call: the user must enter the value of each parameter. The "Tab" key moves from one parameter to the next.
When the selected macro is an empty directive, the full macro call is inserted. When the directive is not empty, only the macro call start tag is inserted: the end tag must be input. Auto-complete enables this content to be input quickly.
External library macro parameters
Auto-complete is also present when inputting a macro's parameters. To do this, place the cursor inside the macro's opening tag (there must be a "space" character before the cursor) and press "Ctrl" + "Space": A list of suggestions is displayed with all the macro parameters and its content is refined as more data is input. Like for snippets, the "Up arrow" and "Down arrow" are used to navigate through the list and "Enter" and "Tab" are used to select.
When a parameter is selected, if it admits predefined values, a list of suggestions is displayed as value input help.
External libraries functions
Help with entering external libraries functions is provided by following the same steps as for the macros. A function must be called inside an interpolation (${...} expression) or as a macro or FreeMarker directive value.
Help with entering a template data model
An APE template handles and displays data transmitted in the form of a data model. Input help can be enabled when accessing the data model tree structure model: auto-complete proposes access to sub-variables when using "dot" notation (triggered by entering the "." character).
This feature requires a data model description model (file in JSON format): By conversion, this file is linked to an APE template and has the name <template_name>_dmodel.json where <template_name> is the name (without the extension .flt or .ftlx) of the associated APE template.
Data model file format
This file is in JSON format. Only the structure of this JSON data is used by input help. Simple-type values (must be entered so as to provide syntactically valid JSON data) are not taken into account.
The JSON structure is identical to that of the jsonDataModel attribute when calling the APE Web mergeDoc service: It is a JSON object whose attributes are the data model's data. An attribute can have a simple (String, Number, Boolean) or complex (Object or Array) JSON type.
This JSON data is therefore "the image" of the jsonDataModel attribute content in a mergeDoc Web service real use case with some differences and limitations:
- Optional data in the data model (i.e. data associated with an attribute which, depending on the real use cases, is not present in the data model) needs to appear in the JSON data if we want it to be proposed by the input help,
- Array-type data can be limited to a single element to simplify the structure: During the structural analysis of Array data, only the first element of the array is taken into account. Input help detects the use of the syntax for accessing an element from Array data (via the [ ... ] notation) but does not analyze the value of the array index (for auto-complete, there is no semantic difference between the following instructions: .data_model.myArray[0], .data_model.myArray[10] and .data_model.myArray[myIndex]),
- The consequence of the previous point is that Array-type data must have homogeneous data: As the analysis is carried out on the first element, input help assumes that all the array elements are of the same type.
Inputting the data model
The data model in an APE template is accessed using the predefined variable .data_model: It represents the data model root. It is a Hash-type object (an associative array) representing the content of the jsonDataModel attribute during a real use case of the template.
When using input help during the template development phase, the .data_model variable represents the content of the JSON data in the data model description file.
The data model description file and template can also be developed in the Visual Studio Code editor: The data model file is loaded and analyzed each time an editor containing an APE template document becomes the active editor (active tab).
However, if the data model description file is modified with another text editor (so without needing to change the active tab in Visual Studio Code), the file can be (re)uploaded via an extension command. To do this, open the command palette with the keyboard shortcut (in Windows) "Ctrl" + "Shift" + "P" then type the "APE Template Editing: Load data model file" command to select it and press "Enter" to enable it.
In the APE template document, the data model input help is triggered after entering the "." character close to the ".data_model" string: A list of suggestions containing root-level attributes is displayed and its content is refined as more data is input. Like for snippets, the "Up arrow" and "Down arrow" are used to navigate through the list and "Enter", "Tab" and "." are used to select.
Once an attribute has been selected, if it is complex type, input help for its constituent attributes can be triggered (if this attribute is Object or Object array-type) by entering the "." character or automatically if it was previously selected with the "." key. (provided that it is Object type).
