ZPT-JS reference - Configuration - declaredRemotePageUrls

Syntax

declaredRemotePageUrls ::= '[' StringLiteral [ ',' StringLiteral ] ']'
StringLiteral          ::= '/'' StringLiteralChar* '/''
StringLiteralChar      ::= any character except '''
                

Description

declaredRemotePageUrls configuration option must be an array of strings with the URLs of the HTML documents containing the external macros.

One of the types of resources preloaded by the preload command are HTML files including external macros. 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 declaredRemotePageUrls configuration option.

Because external macro files must be preloaded before the template is rendered (using the preload 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:

<div data-use-macro="anObject/templateName">
    Macro goes here
</div>
                

If anObject/templateName evaluates to aMacro@macros.html and there is no reference to macros.html in other macro invokations, that macro invokation will throw an exception: Macros in URL 'macros.html' not preloaded!. To resolve this issue we must set manually the list of external macro files we want to use when executing the ZPT call.

Examples

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:

"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.

URLs are by default relative to current URL. You can also use absolute URLs:

"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 ]
    }
});
                

And in your HTML code:

<div data-use-macro="'myMacro@/path/to/your/macro/macros.html'">
    Macro goes here
</div>
                

Context object provides a conf property to set a prefix to all relative URLs:

"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 ]
    }
});
                

Then if you use an URL like macros.html it will be replaced by /path/to/your/templates/macros.html.