Getting started

Quick Start Video

jsreport is an open source reporting server running cross platforms on node.js. It allows to create various reports in various formats like pdf, excel, xml or html. The main idea of jsreport is to let users define reports without lame designers but using code, mostly html and javascript templating engines. This approach gives great power and flexibility to the software developers and let them use the knowledge they already have.

jsreport is fully capable reporting server including advanced features like scheduling, sending reports in emails, authentication, authorization, sub reports, report designer, API, embedded widgets and many other features. It is also greatly extensible what proves growing list of extensions.

This article shows you the most simple use case with jsreport which is creating a pdf invoice and covers basic principles you need to understand to get started.

Basic workflow

  1. get jsreport server
  2. define sample input data
  3. define report template
  4. test and preview report
  5. send real input data into API and get back report

Getting jsreport server

First you need to download and install jsreport into your environment, register for jsreport as a service solution or start right away in jsreport playground.

No matter what option you choose you get access to jsreport html based studio you're going to need for designing and testing reports in this tutorial.

studio

Defining sample data

Before you actually create a pdf invoice layout you should prepare some sample data you will later use to preview it. You can create sample data in jsreport studio from the entity tree panel positioned in the top left. You just need to click the plus button next to the data entry. The sample data needs to be defined in json format and for our super simple invoice it can contain the following:

{
    "to": "Pavel Sladek",
    "from": "Jan Blaha",
    "price": 500
}

sample-data

Defining report template

Report template is together with the rendering process the heart of jsreport. Template defines how the result report is going to look like and is used together with input data every time you render a new report. You can create a report template again from the entity tree panel on the top left.

For the invoice tutorial the first thing you need to do is associate sample data you previously defined with the newly created template.

invoice-data

Recipes

As it was mentioned in the introduction, jsreport supports various reports and various output formats. To specify output format you choose jsreport recipe. Recipe doesn't only define the output format but also how it is produced. You can for example define html template and then just with changing recipe decide if the output should be a pdf, html or excel. Or you don't have to stick with html and use some advanced recipes to create pdf using Apache FOP or excel file from Open XML.

The easiest way to create a pdf invoice is to use html to pdf conversion provided by phantom-pdf recipe, so lets stay with it.

recipe

Templating engines

Templates are defined using common javascript templating engines like jsrender or handlebars. Templating engines lets you assemble reports dynamically using loops, conditions, javascript helpers or data binding. Templating engines basically provides you a way to define any custom report you like.

Every template can use different templating engine and it's up to you which you will choose. They have very similar feature scope and only use different syntax, but every one has different preferences.

Now you can fill the invoice template with html and handlebars. In a very simple way it can look the following:

<h1> Invoice </h1>
<div>
    <span>from: {{from}}</span>
</div>
<div>
    <span>to: {{to}}</span>
</div>
<div>
    <span>price: {{price}}$</span>
</div>

You can see it is just html with handlebars binding to the sample data you previously created. Now you can click the Run button in the jsreport designer and it should preview a pdf in the right pane. This is because you previously selected phantom-pdf which automatically converts html into pdf.

To make it a little bit more complex lets add a tax calculation to the template. To do it you will need to define a custom javascript function calculating tax from the original price. Such a function can be added to the bottom panel in jsreport studio:

function tax(price) {
    return Math.round(price * 0.19);
}

Then back in the top panel you can use the tax function to print the price.

<div>
    <span>tax: {{#tax price}}{{/tax}}$</span></span>
</div>

Finally it should be like this:

Test and preview report

Now it's time to finish the invoice and preview it from the sample data until you are satisfied. You can find a styled and more complex invoice here in the playground if you are lazy.

You might find helpful several features jsreport ships out of the box in the form of extensions during this time. You can for example upload images to report or split bigger template into small child templates. Checkout all jsreport extensions here.

Use API to render report

Now you are ready to integrate your application with jsreport API. It's very simple and in the most cases you just need to do one REST call. You can even try it from your browser's REST plugin.

The following request will invoke rendering previously defined template and response pdf stream back

POST: https://localhost/api/report
Headers: Content-Type: application/json
BODY:

   { 
      "template": { "name" : "invoice-template" },
      "data" : { "to": "Pavel Sladek",     "from": "Jan Blaha",  "price": 800 }
   }

More information about jsrepotr API can be found here.

Further study

To further study I recommend to checkout jsreport playground which provides online set of examples demonstrating the most of the jsreport rendering capabilities. Then you can continue with the next tutorials and explore more advanced features.