Rendering

Render function

Rendering to a web client

The render function is a function on the route object. This function can only be called once per route, subsequent calls are ignored. The function has 2 forms. The first takes one parameter, the render definition object, which specifies how to render the final output of the route. The second has the following signature and translates into a render definition object:

render(in, fn);

One thing to note, although the render definition object looks similar to the when object, it's execution is different in that it's only called once when all when functions are finished.

render definition object

The render definition object has 2 parameters. These parameters are:

{
     params: [],
     fn: function () {}
}

params

required

This specifies the parameters you require. They will be passed to you as an object to the second parameter to your function. Any value not produced during the process phase, or injected will be set to null in the second parameter to fn.

fn

required

The function to execute in the render phase.

fn signature:

function fn(writer, input)

This function will receive a writer (described below) and all the parameters requested as the input object.

The writer object

{
  writeBody: function(body),
  writePartial: function(chunk),
  writeFile: function(type, name, downloadName),
  setHeader: function(name, value),
  setCookie: function(name, value),
  setStatus: function(statusCode),
  done: function()
}

writeBody

function(body)

writeBody takes a string or an object. If body is an object, writeBody calls a safe version of JSON.stringify (one that does not throw on circular references) and returns it as type application/json. If the body is a string it is (by default) returned as 'text/plain' unless you override it with setHeader. When calling writeBody, you do not need to call done. You also do not need to set the content-length. This will be set for you based on the body passed in.

writePartial

function(chunk)

writesPartial takes either a string or a Buffer. If you use writePartial, you are responsible for setting headers such as Content-Length. You also must call done when you're finished.

writeFile

function(type, name, downloadName)

writeFile writes a file to the client. type is set in the header as type (such as 'application/json'). name is the local name of the file. downloadName is the name of the file that should appear in the save-as box in the browser. If you prefer to just send the file to the browser to display (such as a picture), then you may pass null for this value. When calling writeFile, you do not need to call done. You also do not need to set the content-length. This will be set for you based on stating the file passed in.

setHeader

function(name, value)

setHeader is used to set a header value such as Content-Length or Type. You can also use it to set X headers.

setCookie

function(name, value)

setCookie sets a cookie.

setSatus

function(statusCode)

setStatus sets the status code. By default this will be 200, if you want to return something other than 200, you should call this method.

done

function()

done ends the connection. If you use writeBody, you do not need to call this. If you write a response using writePartial then you will need to call this method when you're finished.

Custom Rendering

In some cases you want to completely control render. This may be because you're writing the end result to a Socket.IO room, an email, a file, or somewhere else. In this case you must provide your own writer object. Your writer object may have any methods you choose but MUST have an error method which takes one object.