ZPT-JS reference - Configuration

Syntax

command ::= 'preload' | 'fullRender' | 'partialRender' | 'update'

Description

Defines the action to run. The default is fullRender. Possible values are:

preload. Loads resources using HTTP asynchronously. These resocurces must be preloaded before using them. These resources include:
- Folder dictionaries. Each folder can contain a file (usually named folderDictionary.js) with value/key pairs. To activate this preload set maxFolderDictionaries configuration option to a number greater than 0.
- I18n files. Files containing i18n resources for translating texts, i18n and l10n. To activate this preload set i18n configuration option.
- HTML files including external macros. ZPT-JS will search the files to preload, but some files must be declared using declaredRemotePageUrls configuration option.
fullRender. It does a render of the root element(s).
partialRender. It does a render of the target element(s).
update. It updates the DOM to match one or more changes of the dictionary using the minimum changes. It is mandatory to define a dictionaryChanges configuration. The indexExpressions configuration value must be true (the default value). If it is false an error is thrown.

Examples

An example of fullRender:

import { zpt } from './zpt-esm.js';

var dictionary = {
    ...
};

// Parse template
zpt.run({
    root: document.body,
    dictionary: dictionary,
    command: 'fullRender'
});

This is exactly equivalent to the next example (without setting command, fullRender is the default command):

import { zpt } from './zpt-esm.js';

var dictionary = {
    ...
};

// Parse template
zpt.run({
    root: document.body,
    dictionary: dictionary
});

Sometimes we need to render some DOM elements several times, but not the whole root element. This can be done this way using the partialRender command and defining a target element instead of a root:

import { zpt } from './zpt-esm.js';

var dictionary = {
    ...
};

// First execution: render the body
zpt.run({
    root: document.body,
    dictionary: dictionary
});

[ your code here ]

// Second execution: render only some elements
zpt.run({
    command: 'partialRender',
    target: [ 
        document.getElementById( 'id1' ), 
        document.getElementById( 'id2' )
    ]
});

ZPT-JS provides an alternative to partialRender command: the update command. With this command ZPT-JS updates the DOM inside the root element depending on some changes in the dictionary. To do this ZPT-JS builds an index with data about the expressions and attributes to know the parts of the DOM to update. Let's see an example:

import { zpt } from './zpt-esm.js';

var dictionary = {
    ...
};

// First execution: render the body
zpt.run({
    root: document.body,
    dictionary: dictionary
});

[ your code here ]

// Second execution: update the DOM
zpt.run({
    command: 'update',
    dictionaryChanges: {
        ...
    }
});

ZPT-JS also updates the dictionary with the values in dictionaryChanges. It is shallow copy, not a deep copy.

If we don't use external resources (external macros or i18n files) ZPT-JS executes synchronously: no external file needs to be loaded. But if we use at least one external macro or one i18n file ZPT-JS needs to load one or more external files using HTTP using the preload command. This makes ZPT-JS code executes asynchronously. Keep in mind this!

An example preloading external macro files:

import { zpt } from './zpt-esm.js';

var dictionary = {
    ...
};

zpt.run({
    command: 'preload',
    root: document.body,
    dictionary: dictionary,
    declaredRemotePageUrls: [ 'externalMacros-definitions1.html', 'externalMacros-definitions2.html' ],
    callback: function(){
        zpt.run();
        [ your code here ]
    }
});

First invokation of zpt.run preload externalMacros-definitions1.html and externalMacros-definitions2.html. The second one (inside the callback) renders the HTML after preloading.

An example preloading i18n resources (only one language):

import { zpt } from './zpt-esm.js';

var dictionary = {
    ...
};

zpt.run({
    command: 'preload',
    root: document.body,
    dictionary: dictionary,
    i18n: {
        urlPrefix: './i18n/',
        files: {
            'es': [ 'es1.json', 'es2.json' ]
        }
    },
    callback: function(){
        zpt.run();
        [ your code here ]
    }
});

ZPT-JS reference - Configuration - command

Syntax

Description

Examples