User Defined Code Completion
Introduction
Since the introduction of the Debugger in Layout Developer, the only code auto-complete and hinting available was that for JavaScript and the FOM objects, methods and properties. Template developers create many JavaScript functions (.jf tags) which may be used by other ALD users to create documents and further templates. Providing a more complete view of the code and functions available to end-users is now possible in the debugger using JSDoc and ‘definitions’ files.
Function Tags
The first, and most simple, change in 12.2.0.0 is that the auto-complete feature will now list JavaScript function tags in the auto-complete drop-down which is provided when CTRL+SPACE is pressed in JavaScript tags within the edit window in the Debugger. The list of available function tags will, obviously, only be applicable after content.functions or a variable which refers to this object.
Functions will be shown with the green circled F icon.
Using JSDoc
The code hinting system in the Debugger can use JSDoc to gather information about the objects, functions, methods etc. Although the FOM and JavaScript code hinting is provided by external definitions files (see later), 12.2.0.0 now actively uses JSDoc if it is provided in both declared functions and at the top of function tags (.jf).
• If adding JSDoc to a function tag, it must be at the very top of the tag before any code.
For example at the top of a JavaScript function tag ‘Graphic_start’:
/**
* INSERT A GRAPHIC
* @doc Uses the href and scale attributes on the current element to insert a graphic
*/
var imageTag = arguments[0].attributes.href;
var scale = fFormatting.SCALE_FIT;
Will generate information in the auto-complete list:
And using CTRL+I will provide this information about the function:
• If adding JSDoc to a function declaration inside a tag, the JSDoc must appear before the function declaration. This method will also work if declaring functions globally, from startup.js for example, or if application.loadJS() is used to run an external JavaScript file.
For example, in this code a function is declared with JSDoc preceding it:
/**
* New function func1
* @param arg1 {string} something stringy
* @param arg2 {number} a number
*/
testFuncs.func1 = function(arg1, arg2) {
}
Which will result in:
And this:
Note that definitions using JSDoc might not immediately be updated when creating the code. Give the engine a chance to gather any new definitions. Invalid JSDoc will stop the auto-complete and hinting system from working entirely, so developers are responsible for ensuring correct JSDoc is provided.
From a very basic point of view, JSDoc comments are enclosed within a block comment like this:
/**
* Description
*/
An @doc tag at the beginning of a line, after ‘*’ will provide a documentation block. Arguments can be described using @param tags. Further tags are available. More information about JSDoc can be found here:
https://jsdoc.app/about-getting-started.htmlInternal and External Definitions
The Debugger’s code hinting and auto-complete engine uses JSON-based definitions for both JavaScript (ecma5defs.js) and the FOM (fomdefs.js). In 12.2.0.0 it is now possible to add and manage custom definitions in addition to these. So, if you have created definitions files for your code library, it is now possible to add these dynamically to the definitions in the Debugger.
The JSON structure for definitions will typically start with:
var mydefs = {
"!name": "TESTDEFS",
"!define": {
},
Followed by definitions of each object. Here the ‘var’ declaration is mostly irrelevant. However, the !name property is important as this name can be used to manage definitions (more on this later). The !define declaration is required. In this JSON format, ! prefixed property declarations are special:
• !name — declares the name of the definition set
• !type — declares the type of the property. The type can be one of:
◦ the standard JavaScript types (string, number, bool) — "!type": "number"
◦ another type’s declared in the definitions by prefixing with a ‘+’ — "!type": "+fBlock" if it has a constructor
◦ a function — "!type": "fn(arg1: string, arg2: bool) —> string" where the arguments are given types and the optional return type is specified using the “—>” followed by the type
◦ an array — "!type": "[string]"
◦ an object — "!type": "{prop: type}"
• !doc — allows some documentation to accompany the declaration
• !url — can be used to link the documentation to the an online resource
• !proto — can be used to give the object a custom prototype
Properties not prefixed with an ! are taken to be properties of the objects being defined.
If the definitions are contained within a JavaScript script tag (.js) then they will automatically be picked up by the parser. However, it is possible to load definitions as required from external files.
• application.addTernDefinitions() — this method takes a file path (fPath) argument and will load the definitions the file contains
• application.removeTernDefinitions() — takes a name as the argument which should correspond with the !name property declared in the definition as described above. All definitions associated with that name will be removed from the code completion and hinting functionality
• application.clearTernDefinitions() — will remove all added definitons. The JavaScript and FOM definitions will remain.
