jsreports Developer Guide

jsreports is a JavaScript library that provides on-screen and print report generation for web applications.

See the changelog for latest changes.

See Getting Started for requirements and installation.

Working with data

Your application must define data sources that are available for jsreports to use. Each report definition specifies the ID of its primary data source, and jsreports looks at the corresponding data set when rendering the report.

Data sources can be either JSON or CSV format.

JSON data

jsreports can consume dynamic data served over a REST API, or literal JS objects defined in code. If you need to transform data before handing it to jsreports, it's best to provide data to the report using the data config property of jsreports.render and jsreports.export.

Below is an example of a JSON data feed.

[{
    "person_id": "1x39an4a92y",
    "person_name": "John P. Smith",
    "hours": 4.75
},{
    "person_id": "1ac43L30hR8",
    "person_name": "Alison Jones",
    "hours": 8.5
}]

This is a tabular format represented as an array of row objects. The snippet above corresponds to a table like this:

person_id person_name hours
1x39an4a92y John P. Smith 4.75
1ac43L30hR8 Alison Jones 8.5

CSV data

Here is an example of CSV (comma-separated) text data that represents the same table shown above:

person_id,person_name,hours
1x39an4a92y,John P. Smith,4.75
1ac43L30hR8,Alison Jones,8.5

To define a CSV data source, set the format config property:

{
  id: "sp500",
  name: "S&P 500 Companies",
  url: "data/sp500.csv",
  format: "csv",
  hasHeaderRow: true,
  schema_url: "data/sp500-schema.json"
}

Data source schemas

You should also define a schema for each data source. While it's possible to render reports without a schema, the schema is required in order to use the designer. The schema describes the available columns and their data types.

The most basic schema is an object with a "fields" property, whose value is an array of field definitions, each having a "name" and "type" property. For examples, see the schemas included with the examples in the jsreports distribution.

Here is a sample schema for the data source shown above:

{
    "fields": [{
        "name": "person_id",
        "type": "string"
    },{
        "name": "person_name",
        "type": "string"
    },{
        "name": "hours",
        "type": "number"
    }]
}

Valid data types

The following are the data types allowed for fields in the schema, and examples of their expected representation in the corresponding data source feed:

Data type Example
string "John P. Smith", "Text \"with quotes\""
number 37.56, "37.56"
date "2015-05-19", "2015-05-19 14:22:36"
boolean true, false

Joined data sources

You can join two other data sources together to create a joined data source with its own ID, that can then be used as the basis for a report. The following example creates a joined data source from two other data sources:

{
    "fields": [{
        "id": "states",
        "url": "states.json"
    },{
        "id": "customers",
        "url": "customers.json"
    },{
        "id": "states-and-customers",
        "join": {
            "type": "left",
            "left": "states",
            "leftKey": "state",
            "right": "customers",
            "rightKey": "headquartersState"
        }
    }]
}

In this example, the left data source is a table of states and the right is a table of companies. leftKey and rightKey are the field names from each data source. Rows are joined when the values in those fields are the same between both data sources.

This example uses a left join, meaning that all records from the left data source will be present in the joined results, regardless of whether any records from the right source match that row. To only return joined rows where both sides are present (inner join), use type: "inner".

Report definitions

Reports are stored in a simple JSON text format. Look in the examples directory of the jsreports package for sample report definition files (example: grouping-report-def.json).

Managing saved reports

jsreports includes everything needed to allow users to define and run their own reports. As the developer, you'll need to provide a way to save the report definitions between sessions.

That means that you will need to load the correct set of reports for the current user's session using your own criteria, and you will need to determine a method to save the plain-text report definition on your server when the user edits it in the designer.

Saving report definitions on a server

When the user clicks Save in the designer, jsreports will fire an event that you can listen for. In your event handler, you can send the report definition to your server and store it in a database.

Example: 

// Note: designer is a variable that has been initialized 
//    as in step 3 of Getting Started, above.
$(designer).on("save", function(evt, reportdef) {
    // reportdef is a string containing the report 
    //    definition in JSON format
    // currentUserID is an example variable that would 
    //    identify the current user
    $.post("/save-report.php", { 
      report: reportdef, 
      userid: currentUserID 
    }, function(data) {
        alert("Report saved on server.");
    });
});

Running reports

If you have a report definition in a string variable, either loaded from your server or captured in the Save event of the designer, you can run it (generate the report output in HTML format) by using the following code:

// reportDef is the string containing the report 
//    definition in JSON form
// dataSources is a Javascript array of data sources, 
//    exactly the same as passed in step 3 of 
//    Getting Started, above
// target is a div element on the page into which 
//    the report will be rendered
jsreports.render({
    report_def: reportDef,
    target: $("#report-output"),
    datasets: dataSources
});

Images

You can provide a selection of images for your users to embed in reports. Just pass an "images" configuration property when instantiating a designer, like this:

// images is an array of image definition objects, 
// with name and url properties
var designer = new jsreports.Designer({
    images: [{
        name: "ACME logo",
        url: "/images/acme-logo.jpg"
    },{
        name: "Product photo",
        url: "/images/product1.jpg"
    }],
    /* ... */
});

NOTE: In order for images to appear in browser-generated PDF reports, the URL of the image must be on the same domain as the page from which the report is generated, due to browser cross-origin security policy. Using relative URLs, as in the code snippet above, is one way to solve this problem.

Fonts and PDF

PDF's built-in fonts do not support the character range required to display all non-English alphabets. Therefore, by default jsreports attempts to embed and use the font Roboto (from Google) as the default font when generating a PDF.

jsreports looks for the Roboto font under the /fonts path relative to the jsreports.libraryPath variable.

If you include jsreports in your page via a <script> tag, jsreports may be able to infer the libraryPath correctly. If you find that international characters are not appearing properly in your PDF, try manually setting the library path as follows:

jsreports.libraryPath = '/path/to/jsreports';

The path should be to a folder containing the "media" and "fonts" subfolders from the jsreports distribution.

You may also need to check the network requests being made during PDF rendering to verify that requests are being made to load Roboto.

API Reference

See the API Reference for details on available classes and methods.

Working with Jasper Reports

See How to use jsreports with Jasper Reports.

Data source configuration reference

The following options can be defined on a data source:

Property Description
idstring The ID used internally to refer to the data source. This ID will appear in the report definition when the report uses this data source.
namestring A human-friendly name for the data source, for use in the designer.
urlstring A URL from which the (JSON) data should be fetched. Data is expected to be in the form of a JSON array of row objects.
OPTIONAL
schema_urlstring URL from which to fetch the JSON schema object describing the data source.
OPTIONAL
dataArray An array of row objects containing the data for the data source. Use this property when you want to load the data yourself (and possibly transform it before feeding it to jsreports).
OPTIONAL
schemaObject The schema object describing the data source. You can use this instead of schema_url to pass the schema object directly.
OPTIONAL
postProcessFunction: (Array) => Array A function that will be called after loading the data source and before using it in the report. The function receives the loaded array of row objects and should return an array of row objects. This provides a way to transform or filter data before providing it to the report.
OPTIONAL
formatstring: ["csv", "json"] The format of the data. If "json" (or not provided), a JSON array of row objects is expected. If "csv", a comma-separated text file is expected.
OPTIONAL