Never-ending Pumpkin Mulch

    toner

    0.1.6 • Public • Published

    jsreport toner

    Build Status

    node library for dynamic assembling documents and printing them into various formats (written for jsreport)

    var toner = require("toner")();
    toner.engine("jsrender", require("toner-jsrender"));
    toner.recipe("wkhtmltopdf", require("toner-wkhtmltopdf")());
     
    toner.render({
        template: { 
            engine: "jsrender",
            recipe: "wkhtmltopdf", 
            content: "<h1>{{:foo}}</h1>"
        },
        data: { foo: "hello world"}
    }, function(err, res) {
        var pdfbuffer = res.content;
        var pdfstream = res.stream;    
    });

    Basics

    Engines

    Documents are assembled using javascript templating engines. The engine needs to be first registered in toner.

    toner.engine("[engine name]", pathToEngineScript);

    You can write your own engine or use an existing one:

    Note that templating engine runs safely in another sand-boxed process. You don't have to be afraid to run user defined templates. See script-manager for details.

    You can register and use none engine to skip its processing:

    toner.engine('none', toner.noneEngine);
    toner.render({
      template: {
        engine: 'none'   
        ...
      }

    Recipes

    The actual printing of the document into pdf, excel or any other type of the document is done by something we call recipe. The recipe also needs to be registered first.

    toner.recipe("[recipe name]", function(req, res) { ... });

    You can also write your own recipe or use an existing one:

    You can use html recipe to simply produce html:

    toner.recipe("html", toner.htmlRecipe);
    toner.render({
      template: {
        recipe: 'html'   
        ...
      }

    Render

    The complete document generation is invoked using toner.render function:

    toner.render({
        template: { 
            engine: "jsrender",
            recipe: "wkhtmltopdf", 
            content: "<h1>{{:foo}}</h1>"
        },
        data: { foo: "hello world"}
    }, function(err, res) {
        var pdfbuffer = res.content;
        var pdfstream = res.stream;    
    });

    The only parameter is an object representing rendering request. The request has following structure:

    {
        //[required]
        template: { 
            //[required] templating engine used to assemble document
            engine: "jsrender",
            //[required] recipe used for printing previously assembled document
            recipe: "wkhtmltopdf", 
            //[required] template for the engine
            content: "<h1>{{:foo}}</h1>",
            //javascript helper functions used by templating engines
            helpers: "function foo() { ...}" + 
                     "function foo2() { ... }"
            //any other settings used by recipes  
            ...  
        },
        //dynamic data inputs used by templating engines
        data: { foo: "hello world"}
        ...
    }

    The render callback then contains the response with

    {
        //node.js buffer with the document
        content: ...
        //stream with the document
        stream: ...
        //http response headers with valid content type..
        headers: { ... }
    }

    Pipe the document to the http response

    var http = require('http');
    http.createServer(function (req, res) {
        toner.render({...}, function(err, out) {
            out.stream.pipe(res);
        });
    }).listen(1337, '127.0.0.1');

    Hooks

    It is expected there will soon popup other packages hooking into the Toner and adding additional functionality. For this case Toner provides several hooks which can be used to extend it.

    toner.before(function(req, res, cb) { ... });
    toner.after(function(req, res, cb) { ... });
    toner.afterEngine(function(req, res, cb) { ... });

    Options

    Calling Toner accepts some options as the parameter

    var toner = require("toner")({ ... });

    Possible options:

    • tempDirectory - this attribute is used by the recipes to store temporary files
    • options passed to the script-manager depndency

    Tests

    npm install
    npm test

    Contributions

    Yes, please.

    License

    MIT

    Install

    npm i toner

    DownloadsWeekly Downloads

    2

    Version

    0.1.6

    License

    MIT

    Last publish

    Collaborators

    • pofider