JavaScript API // Marko

Table of Contents

require('marko')

Methods

load(templatePath[, templateSrc][, options]) : Template

Loads a template instance for the given template path. Both templateSrc and options are optional.

Template loading is supported in the browser and on the server but the behavior differs slightly.

On the server, if templateSrc is not provided then templatePath is expected to be the path to a Marko template file. If templateSrc is provided then it is expected to be a String and its value will be the raw template. The templatePath argument is only used for reporting error stack traces if templateSrc is provided.

In the browser, templatePath is expected to path to be the module name of the compiled template and the module will be loaded via require(templatePath). The templateSrc argument is ignored if the load function is called in the browser.

If options is provided then it is expected to be the last argument and should be an Object.

Example usage for browser and server:

var templatePath = require.resolve('./template.marko');
var template = require('marko').load(templatePath);
template.render({ name: 'Frank' }, process.stdout);

Example server-side template loading with writeToDisk: false option:

var templatePath = './sample.marko';
var template = require('marko').load(templatePath, {writeToDisk: false});
template.render({ name: 'Frank' }, process.stdout);

Example server-side template compilation from string:

var templatePath = 'sample.marko';
var templateSrc = 'Hello $!{data.name}';
var template = require('marko').load(templatePath, templateSrc);
template.render({ name: 'Frank' }, process.stdout);

Supported options:

createWriter([stream]) : AsyncWriter

Creates an instance of an AsyncWriter instance that can be used to support asynchronous rendering.

Example usage:

var out = require('async-writer').create(process.stdout);
out.write('Hello');

var asyncOut = out.beginAsync();
setTimeout(function() {
    asyncOut.write('World')
    asyncOut.end();
}, 100);

require('./template.marko').render({}, out);

render(templatePath, templateData, stream.Writable)

Deprecated. Do not use.

render(templatePath, templateData, callback)

Deprecated. Do not use.

stream(templatePath, templateData) : stream.Readable

Deprecated. Do not use.

Properties

helpers

Global helpers passed to all templates. Available in compiled templates as the __helpers variable. It is not recommended to use this property to introduce global helpers (globals are evil).

Template

The Template type.

Template

Methods

renderSync(templateData) : String

Synchronously renders a template to a String.

NOTE: If out.beginAsync() is called during synchronous rendering an error will be thrown.

Example usage:

var template = require('./template.marko');
var html = template.renderSync({ name: 'Frank' });
console.log(html);

render(templateData, stream.Writable)

Renders a template to a writable stream.

Example usage:

var template = require('./template.marko');
template.render({ name: 'Frank' }, process.stdout);

render(templateData, AsyncWriter)

Renders a template to an AsyncWriter instance that wraps an underlying stream.

Example usage:

var template = require('./template.marko');
var out = require('marko').createWriter(process.stdout);
template.render({ name: 'Frank' }, out);

render(templateData, callback)

Asynchronously renders a template and provides the output to the provided callback function.

var template = require('./template.marko');
template.render({ name: 'Frank' }, function(err, html, out) {
    if (err) {
        // Handel the error...
    }

    console.log(html);
});

NOTE: The out argument will rarely be used, but it will be a reference to the AsyncWriter instance that was created to facilitate rendering of the template.

stream(templateData) : stream.Readable

Returns a readable stream that can be used to read the output of rendering a template.

Example usage:

var template = require('./template.marko');
template.stream({ name: 'Frank' }).pipe(process.stdout);

require('marko/compiler')

Methods

createCompiler(path, options) : TemplateCompiler

Creates a compiler for a given template path and given options.

compile(src, path, options, callback)

Compiles a template given the loaded template source, the file system path of the source template and options. Currently, compilation is synchronous so the callback is optional. In the future, we may allow asynchronous compilation.

The result will be the compiled JavaScript source code.

compileFile(path, options, callback)

Compiles a template given the loaded template source, the file system path of the source template and options. Currently, compilation is synchronous so the callback is optional. In the future, we may allow asynchronous compilation.

The result will be the compiled JavaScript source code.

getLastModified(path, options, callback)

Compiles a template given the loaded template source, the file system path of the source template and options. Currently, this method is synchronous so the callback is optional. In the future, we may allow this method to be asynchronous.

Returns the last modified time as a number.

clearCaches()

Clears any internal caches used by the compiler. Needed for hot-reloading.

Properties

defaultOptions

The default options used by the compiler. These options can be changed as shown in the following sample code:

require('marko/compiler').defaultOptions.writeToDisk = false;

Default options:

{
    /**
     * Set of tag names that should automatically have whitespace preserved.
     * Alternatively, if value is `true` then whitespace will be preserved
     * for all tags.
     */
    preserveWhitespace: {
        'pre': true,
        'textarea': true,
        'script': true
    },
    /**
     * Set of tag names that should be allowed to be rendered as a self-closing
     * XML tag. A self-closing tag will only be rendered if the tag has no nested
     * content. HTML doesn't allow self-closing tags so you should likely
     * never use this.
     */
    allowSelfClosing: {},
    /**
     * Set of tag names that should be rendered with a start tag only.
     */
    startTagOnly: {
        'img': true,
        'br': true,
        'input': true,
        'meta': true,
        'link': true,
        'hr': true
    },
    /**
     * If true, then the compiler will check the disk to see if a previously compiled
     * template is the same age or newer than the source template. If so, the previously
     * compiled template will be loaded. Otherwise, the template will be recompiled
     * and saved to disk.
     *
     * If false, the template will always be recompiled. If `writeToDisk` is false
     * then this option will be ignored.
     */
    checkUpToDate: true,
    /**
     * If true (the default) then compiled templates will be written to disk. If false,
     * compiled templates will not be written to disk (i.e., no `.marko.js` file will
     * be generated)
     */
    writeToDisk: true
}