marko/docs/02-rendering.md

Rendering

To render a Marko view, you need to require it.

example.js

var button = require('button.marko');

Note: If you are targeting node.js, you will need to enable the require extension in order to require .marko files. If you are targeting the browser, you will need to use a bundler like lasso, webpack, browserify or rollup.

Once you have a view, you can pass input data and render it:

example.js

var button = require('button.marko');
var html = button.renderToString({ label:'Click me!' });

console.log(html);

The input data becomes available as input within a view, so if button.marko looked like this:

button.marko

<button>${input.label}</button>

The output HTML would be:

<button>Click me!</button>

Rendering methods

We used the renderToString method above to render the view, but there are a number of different method signatures that can be used to render.

Many of these methods return a RenderResult which is an object with helper methods for working with the rendered output.

renderSync(input)

params	type	description
input	Object	the input data used to render the view
return value	RenderResult	The result of the render

Using renderSync forces the render to complete synchronously. If a tag attempts to run asynchronously, an error will be thrown.

var view = require('./view.marko');
var result = view.renderSync({});

result.appendTo(document.body);

render(input)

params	type	description
input	Object	the input data used to render the view
return value	AsyncStream/AsyncVDOMBuilder	the async out render target

The render method returns an async out which is used to generate HTML on the server or a virtual DOM in the browser. In either case, the async out has a then method that follows the Promises/A+ spec, so it can be used as if it were a Promise. This promise resolves to a RenderResult.

var view = require('./view.marko');
var resultPromise = view.render({});

resultPromise.then((result) => {
    result.appendTo(document.body);
});

render(input, callback)

params	type	description
input	Object	the input data used to render the view
callback	Function	a function to call when the render is complete
callback value	RenderResult	The result of the render
return value	AsyncStream/AsyncVDOMBuilder	the async out render target

var view = require('./view.marko');

view.render({}, (err, result) => {
    result.appendTo(document.body);
});

render(input, stream)

params	type	description
input	Object	the input data used to render the view
stream	WritableStream	a writeable stream
return value	AsyncStream/AsyncVDOMBuilder	the async out render target

The HTML output is written to the passed stream.

var http = require('http');
var view = require('./view.marko');

http.createServer((req, res) => {
    res.setHeader('content-type', 'text/html');
    view.render({}, res);
});

render(input, out)

params	type	description
input	Object	the input data used to render the view
out	AsyncStream/AsyncVDOMBuilder	The async out to render to
return value	AsyncStream/AsyncVDOMBuilder	The out that was passed

The render method also allows passing an existing async out. If you do this, render will not automatically end the async out (this allows rendering a view in the middle of another view). If the async out won't be ended by other means, you are responsible for ending it.

var view = require('./view.marko');
var out = view.createOut();

view.render({}, out);

out.on('finish', () => {
    console.log(out.getOutput());
});

out.end();

renderToString(input)

params	type	description
input	Object	the input data used to render the view
return value	String	The HTML string produced by the render

Returns an HTML string and forces the render to complete synchronously. If a tag attempts to run asynchronously, an error will be thrown.

var view = require('./view.marko');
var html = view.renderToString({});

document.body.innerHTML = html;

renderToString(input, callback)

params	type	description
input	Object	the input data used to render the view
callback value	String	The HTML string produced by the render
return value	undefined	N/A

An HTML string is passed to the callback.

var view = require('./view.marko');

view.renderToString({}, (err, html) => {
    document.body.innerHTML = html;
});

stream(input)

The stream method returns a node.js style stream of the output HTML. This method is available on the server, but is not available by default in the browser. If you need to use streams in the browser, you may require('marko/stream') as part of your client-side bundle.

var fs = require('fs');
var view = require('./view.marko');
var writeStream = fs.createWriteStream('output.html');

view.stream({}).pipe(writeStream);

RenderResult

getComponent()

getComponents(selector)

afterInsert(doc)

getNode(doc)

getOutput()

toString()

toJSON()

appendTo(targetEl)

insertAfter(targetEl)

insertBefore(targetEl)

prependTo(targetEl)

replace(targetEl)

replaceChildrenOf(targetEl)

Global data

If you need to make data available globally to all views that are rendered as the result of a call to one of the above render methods, you can pass the data as a $global property on the input data object. This data will be removed from input and merged into the out.global property.

view.render({
    $global: {
        flags: ['mobile']
    }
});