zpt
Version:
Zenon Page Templates - JS (ZPT-JS)
143 lines (126 loc) • 6.04 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>ZPT-JS reference - Configuration - declaredRemotePageUrls</title>
<script type="text/javascript" src="../lib/zpt.min.js" defer></script>
<script type="text/javascript" src="../js/zpt.js" defer></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 - declaredRemotePageUrls</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">
declaredRemotePageUrls ::= '[' StringLiteral [ ',' StringLiteral ] ']'
StringLiteral ::= '/'' StringLiteralChar* '/''
StringLiteralChar ::= any character except '''
</pre>
<h2 data-attributes="id 'description'">Description</h2>
<p>
<em>declaredRemotePageUrls</em> configuration option must be an array of strings with the URLs of the HTML documents containing the external macros.
</p>
<p>
One of the types of resources preloaded by the <a href="configuration-command.html">preload</a> command are <em>HTML files including external macros</em>. ZPT-JS will search the files to preload if you use literals to define them in the template, but if you use another type of expression ZPT-JS will not be able to preload them. In these cases you must declare these files using <em>declaredRemotePageUrls</em> configuration option.
</p>
<p>
Because external macro files must be preloaded before the template is rendered (using the <a href="configuration-command.html">preload</a> command), ZPT-JS must to know the list of external files invoked in the template. If we use literal string expressions or expressions that can be evaluated using only dictionary there is nothing to do. But if we use an expression that can not be resolved at first like this:
</p>
<pre class="brush: html">
<div data-use-macro="anObject/templateName">
Macro goes here
</div>
</pre>
<p>
If <code>anObject/templateName</code> evaluates to <code>aMacro@macros.html</code> and there is no reference to <code>macros.html</code> in other macro invokations, that macro invokation will throw an exception: <code>Macros in URL 'macros.html' not preloaded!</code>. To resolve this issue we must set manually the list of external macro files we want to use when executing the ZPT call.
</p>
<h2 data-attributes="id 'examples'">Examples</h2>
<p>
If we don't use external macros ZPT-JS executes synchronously: no external file needs to be loaded. But if we use at least one external macro ZPT-JS needs to load one or more external files using HTTP. This makes ZPT-JS code executes asynchronously. Keep in mind this! To deal with this take a look at:
</p>
<pre class="brush: js; highlight: [13]">
"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 ]
}
});
</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>
URLs are by default relative to current URL. You can also use absolute URLs:
</p>
<pre class="brush: js; highlight: [13]">
"use strict";
var zpt = require( 'zpt' );
var dictionary = {
...
};
zpt.run({
command: 'preload',
root: document.body,
dictionary: dictionary,
declaredRemotePageUrls: [ '/path/to/your/macro/macros.html' ],
callback: function(){
zpt.run();
[ your code here ]
}
});
</pre>
<p>
And in your HTML code:
</p>
<pre class="brush: html">
<div data-use-macro="'myMacro@/path/to/your/macro/macros.html'">
Macro goes here
</div>
</pre>
<p>
<em>Context</em> object provides a conf property to set a prefix to all relative URLs:
</p>
<pre class="brush: js; highlight: [9]">
"use strict";
var zpt = require( 'zpt' );
var dictionary = {
...
};
zpt.context.getConf().externalMacroPrefixURL = '/path/to/your/templates/';
zpt.run({
command: 'preload',
root: document.body,
dictionary: dictionary,
declaredRemotePageUrls: [ 'macros.html' ],
callback: function(){
zpt.run();
[ your code here ]
}
});
</pre>
<p>
Then if you use an URL like <em>macros.html</em> it will be replaced by <em>/path/to/your/templates/macros.html</em>.
</p>
</article>
</div>
</body>
</html>