Template file (*.tmpl)

The template file (* .tmpl) is the main rendering description file and contains three types of sections describing options, data and the template itself. For ease of development, it is easier to create a template either using the SublimeFCFPlugin, VSCodeFCFFramework plugins or the command:

$ fcfmngr create template-file [TEMPLATE_NAME] [SUPER_NAME]

Where:

TEMPLATE_NAME - Name of the new template

SUPER_TEMPLATE - The path to the base template. Optional parameter

Before examining the structure of a template in detail, let's give an example of it:

//~OPTIONS { // Basic inheritance template // Default: undefined // extends:"", // Automatic template update mode when the argument changes. // Acceptable values: // true|"all" - The update is performed on any change // "external" - The update is performed only if the external template was the initiator of the change. // false - The template is not being updated // The option can be overridden by the fcfAutoUpdate template argument. // Default: false autoUpdate: false, // If true, the rendering is performed on the client side. // Acceptable values: // true|"all" - Rendering is done on the client, when done on the browser side // "update" - The first render is done on the server side and the update is on the client side // "update_np" - The first render is done on the server side and the update is on the client side. // Parameters of the programmable type are not recalculated. // false - Rendering is always done on the server side // This parameter can be overridden by the fcfClientRendering template argument, but only if the option is true. // Default: false clientRendering: false, // Additional JS & CSS files to connect (JS files are also connected on the server side) // Default: [] include: [], // Plug-in additional JS & CSS files on the client side // Default: [] clientInclude: [], // [Since 1.1.43] DOM elements merge flag. // If true, then existing items are not replaced when updated, but updated. // Default: false merge: false, // If the parameter is false, the template is not wrapped in a container, // a wrapper is not created for it, and its arguments are not available on the client. // Default: true wrapper: true, // The template is displayed when the template is locked or false, // then the lock is performed only by the transparent container. // If the option is true, then @controls:lock is used. // The option can be overridden by the fcfLockTemplate template argument. // Default: true lockTemplate: true } //~ARGUMENTS { } //~TEMPLATE <h1>Hello wonderful world!</h1>

As mentioned earlier, the template has three sections. Each section starts with //~. Accordingly, we have sections OPTIONS, ARGUMENTS and TEMPLATE. Only the TEMPLATE section is required, the rest of the sections may not be declared.

OPTIONS section

The OPTIONS section contains an object with a description of template options that do not change and describe its main program characteristics.

Template option values on the client are available through the fcf.NClient.Wrapper.getOptions() method. The description of the main options of the template is given below.

extends option Contains the path to the base template from which the current one inherits. When a template is inherited, the OPTIONS and ARGUMENTS values are overloaded, and the contents of the template and sub-templates are replaced by the inheritor. autoUpdate option Template auto-update mode when changing its arguments. It can take one of several values:
  • true|"all" - The template is updated whenever the template argument changes by calling Wrapper.setArg()
  • "external" - A template update is performed when a template argument is changed that is initiated by external code and the change is not performed from a nested template. This mode is used when building the internal logic of the template visualization.
  • false - Template update fails when arguments change

The parameter can be overridden using the fcfAutoUpdate template argument.

Default value: false

clientRendering option

Render permission on the client. List of acceptable values:

  • true|"all" - Rendering and updating called on the browser side is done on the browser side.
  • "update" - The first rendering is done on the server side and the update is done on the browser side.
  • "update_np" - The first rendering is done on the server side and the update is done on the browser side. Program arguments are not recalculated when upgraded.
  • false - Rendering Performed on the server side only

The parameter can be overridden using the fcfClientRendering template argument.

Default value: false

include option Array of JS and CSS files to be connected. JS files are also connected on the server side. clientInclude option An array of JS and CSS files to be connected, only on the browser side. merge option [С версии 1.1.43] The DOM tree merge flag when updating the template. If true, then the existing elements are not replaced during the update, but are updated.

Default value: false

wrapper option [Since version 1.1.36] Flag for creating a wrapper for the template. If the parameter is false, the template is not packaged in a container, a wrapper is not created for it, and its arguments are not available on the client.

Default value: true

lockTemplate option The template displayed when blocking with the Wrapper.lock() method or false, then the blocking is performed only by the transparent container. If an option is not specified or true, the @controls:lock pattern is used. The parameter can be overridden using the fcfLockTemplate template argument.

Default value: true

ARGUMENTS section

The ARGUMENTS section stores an object with template arguments. Arguments can be simply the value or the result of one of the functions fcf.argVal(), fcf.argUrl(), fcf.argRef(), fcf.argRecordRef(), fcf.argProg(). Arguments presented in the form of a value do not undergo any processing and are supplied to the template in the form as presented, over the other types of arguments are pre-assembled and tokenized. For more details about specialized arguments, we advise you to read the corresponding documentation pages to which the above functions refer.

All template arguments are available in the body of the template through the args variable.

Example:

//~ARGUMENTS { title: "first page", description: fcf.argProg(), } //~TEMPLATE <h2>@{{args.title}}@</h2> @{{args.description}}@ System arguments

In addition to user-defined arguments, there are system arguments that start with the fcf prefix. Below is their description and purpose:

  • string fcfId - template identifier
  • string fcfClass - CSS classes added to the template header
  • string fcfClassInner - CSS classes added to the header of the template. This argument should only be used inside a template declaration and should not be overloaded by an external renderer.
  • string fcfStyle - CSS styles added to the template header
  • string fcfStyleInner - CSS styles added to the header of the template. This argument should only be used inside a template declaration and should not be overloaded by an external renderer.
  • bool|string fcfAutoUpdate - overloads the autoUpdate template option value
  • bool|string fcfClientRendering - overloads the clientRendering template option value
  • false|undefined|string fcfLockTemplate - overloads the value of the template option lockTemplate
  • string fcfEvent[EVENT_NAME] - DOM event handling variables of template action element. The variable name begins with the fcfEvent prefix, followed by the event name with a capital letter. The value is a string with Javascript code, in which the following variables are available:

    • Event event - Event object
    • fcf.NClient.Wrapper wrapper - Template wrapper object
    • fcf.NClient.Wrapper parent - Template parent wrapper

    Example:

    //~ARGUMENTS { fcfEventClick: "wrapper.onClick()", }

When using argument tokenization in a tokenizer, the following predefined variables are available

  • object args - template arguments object
  • object decor - an object containing the decoration classes. The key is the code name of the class group, and the value is a string containing CSS design classes. Formed by themes. The functionality of the themes has not yet been fully implemented.
  • fcf.RouteInfo route - route information object

Example:

//~ARGUMENTS { val1: "12345", val2: fcf.argVal("@{{args.val1}}@6789"), } //~TEMPLATE @{{args.val2}}@

Result:

123456789 TEMPLATE section

In the template section, the rules for generating HTML are written.

The template section has three control constructs: %{{ }}% code construct, @{{ }}@ output construct and !{{ }}! translate construct

Code construction %{{ }}% This block contains the Javascript control code. When using blocks if, while, for and others inside which the break of the construction %{{ }}% is used, brackets { } should be used Translation construct !{{ }}! Outputs text to a template using translation to the user's language.

Example

!{{Hello world}}! Output construct @{{ }}@ This block performs data output to the body of the template.

Example

%{{ let array = ["first", "second", "third"]; for(let i = 0; i < array.length; ++i) { }}% <p>@{{array[i]}}@</p> %{{ } }}%

Result

<p>first</p> <p>second</p> <p>third</p>

As you can see, the mechanism for creating a template is very simple. The template also supports the use of asynchronous operations - the await construct.

In addition to user-defined variables, the following variables are available in the template:

  • object args - template arguments object
  • object decor - an object containing the decoration classes. The key is the code name of the class group, and the value is a string containing CSS design classes. Formed by themes. The functionality of the themes has not yet been fully implemented.
  • fcf.RouteInfo route - route information object
  • fcf.NRender.NDetails.TemplateRender render - The internal renderer of the template.
Declaring events in a template

In addition to the standard method of declaring event handlers of the DOM element, the developer can declare events via the fcfEvent[EVENT_NAME] attributes. Unlike regular events, additional variables are available in the event handler code:

  • Event event - Event object
  • fcf.NClient.Wrapper wrapper - Template wrapper object
  • fcf.NClient.Wrapper parent - Template parent wrapper

Пример:

//~TEMPLATE <a fcfEventClick="wrapper.onClick(event)">Link</a> Subtemplates

In addition to the main sections, subtemplate sections can be declared in the template. They are declared in the same way as the main sections, only after the section type, followed by a space, the name of the subtemplate.

To render the subtemplate, a path is used that has the format: [MAIN_TEMPLATE_PATH]+[SUBTEMPLATE_NAME]

Where:

MAIN_TEMPLATE_PATH - path to the main template

SUBTEMPLATE_NAME - Subtemplate name

If rendering is performed inside the main template, then the full path may not be specified: +[SUBTEMPLATE_NAME]

Here's an example of a template:

//~TEMPLATE <h1>Example of the simple list</h1> %{{ let list = [ {name: "first", value: "value 1"}, {name: "second", value: "value 2"}, {name: "third", value: "value 3"}, ]; list.forEach((a_item)=>{ }}% @{{ render.template("+item", {value: a_item}) }}@ %{{ }); }}% //~TEMPLATE item <div> <b>@{{args.value.name}}@</b> - @{{args.value.value}}@ </div>

Result:

<h1>Example of the simple list</h1> <div> <b>first</b> - value 1 </div> <div> <b>second</b> - value 2 </div> <div> <b>third</b> - value 3 </div>

As you can see from the example, the child template is rendered through the "+item" path:

render.template("+item", {value: a_item})