zpt
Version:
Zenon Page Templates - JS (ZPT-JS)
198 lines (173 loc) • 7.65 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>ZPT-JS reference - Configuration - command</title>
<script type="module" src="../js/zpt.js"></script>
<script type="text/javascript" src="../lib/syntaxHighlighter/lib.js"></script>
<link rel="stylesheet" type="text/css" href="../docs.css">
<link rel="stylesheet" type="text/css" href="../lib/syntaxHighlighter/theme.css">
</head>
<body>
<div data-use-macro="'page@templates.html'">
<div data-fill-slot="'page-header'">
<h1>ZPT-JS reference - Configuration - command</h1>
<ul>
<li><a href="#syntax">Syntax</a>.</li>
<li><a href="#description">Description</a>.</li>
<li><a href="#examples">Examples</a>.</li>
</ul>
</div>
<article data-fill-slot="'article'">
<h2 data-attributes="id 'syntax'">Syntax</h2>
<pre class="syntax">
command ::= 'preload' | 'fullRender' | 'partialRender' | 'update'
</pre>
<h2 data-attributes="id 'description'">Description</h2>
<p>
Defines the action to run. The default is <em>fullRender</em>. Possible values are:
</p>
<ul>
<li>
<em>preload</em>. Loads resources using HTTP asynchronously. These resocurces must be preloaded before using them. These resources include:
<ul>
<li><em>Folder dictionaries</em>. Each folder can contain a file (usually named <em>folderDictionary.js</em>) with value/key pairs. To activate this preload set <a href="configuration-maxFolderDictionaries.html">maxFolderDictionaries</a> configuration option to a number greater than 0.</li>
<li><em>I18n files</em>. Files containing i18n resources for translating texts, i18n and l10n. To activate this preload set <a href="configuration-i18n.html">i18n</a> configuration option.</li>
<li><em>HTML files including external macros</em>. ZPT-JS will search the files to preload, but some files must be declared using <a href="configuration-declaredRemotePageUrls.html">declaredRemotePageUrls</a> configuration option.</li>
</ul>
</li>
<li><em>fullRender</em>. It does a render of the <a href="configuration-root.html">root</a> element(s).</li>
<li><em>partialRender</em>. It does a render of the <a href="configuration-target.html">target</a> element(s).</li>
<li><em>update</em>. It updates the DOM to match one or more changes of the dictionary using the minimum changes. It is mandatory to define a <a href="configuration-dictionaryChanges.html">dictionaryChanges</a> configuration. The <a href="configuration-indexExpressions.html">indexExpressions</a> configuration value must be <code>true</code> (the default value). If it is <code>false</code> an error is thrown.</li>
</ul>
<h2 data-attributes="id 'examples'">Examples</h2>
<p>
An example of <em>fullRender</em>:
</p>
<pre class="brush: js; highlight: [13]">
import { zpt } from './zpt-esm.js';
var dictionary = {
...
};
// Parse template
zpt.run({
root: document.body,
dictionary: dictionary,
command: 'fullRender'
});
</pre>
<p>
This is exactly equivalent to the next example (without setting command, <em>fullRender</em> is the default command):
</p>
<pre class="brush: js">
import { zpt } from './zpt-esm.js';
var dictionary = {
...
};
// Parse template
zpt.run({
root: document.body,
dictionary: dictionary
});
</pre>
<p>
Sometimes we need to render some DOM elements several times, but not the whole root element. This can be done this way using the <em>partialRender</em> command and defining a <em>target</em> element instead of a <em>root</em>:
</p>
<pre class="brush: js; highlight: [17]">
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' )
]
});
</pre>
<p>
ZPT-JS provides an alternative to <em>partialRender</em> command: the <em>update</em> 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:
</p>
<pre class="brush: js; highlight: [17]">
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: {
...
}
});
</pre>
<p>
ZPT-JS also updates the dictionary with the values in <em>dictionaryChanges</em>. It is shallow copy, not a deep copy.
</p>
<p>
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 <em>preload</em> command. This makes ZPT-JS code executes asynchronously. Keep in mind this!
</p>
<p>
An example preloading external macro files:
</p>
<pre class="brush: js; highlight: [8]">
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 ]
}
});
</pre>
<p>
First invokation of <em>zpt.run</em> preload <em>externalMacros-definitions1.html</em> and <em>externalMacros-definitions2.html</em>. The second one (inside the callback) renders the HTML after preloading.
</p>
<p>
An example preloading i18n resources (only one language):
</p>
<pre class="brush: js; highlight: [8]">
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 ]
}
});
</pre>
</article>
</div>
</body>
</html>