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 isfalse
an error is thrown.
Examples
An example of fullRender:
"use strict"; var zpt = require( 'zpt' ); 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):
"use strict"; var zpt = require( 'zpt' ); 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:
"use strict"; var zpt = require( 'zpt' ); 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:
"use strict"; var zpt = require( 'zpt' ); 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:
"use strict"; var zpt = require( 'zpt' ); 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):
"use strict"; var zpt = require( 'zpt' ); 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 ] } });