Embedding

Update: This extension is not compatible with jsreport >= 1.0. The similiar functionality is now part of jsreport browser client and html with browser client recipe.

Link jsreport browser sdk into your page and easily render a report from the browser or open limited version of jsreport studio inside any web application and let end users to customize their reports. There are various scenarios where this can be used. Typical example can be when application is sending invoices to the customers and allows them to modify invoice template to the required design.

Getting started

To start using jsreport browser sdk you need to:

  1. Include jquery into page
  2. Include jsreport embed.js into page
  3. Create jsreportInit function in the global scope with similar meaning as $.ready
  4. Use global object jsreport to open editor or render a template
<!DOCTYPE html>
<html>
<head lang="en">
    <!-- jquery is required for jsreport embedding -->
    <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
    <script src="http://local.net:2000/extension/embedding/public/js/embed.js"></script>
</head>
<body>
    <script>
        //jsreport will call jsreportInit function from global scope when its initialized
        jsreportInit = function () {
            //use jsreport object to render reports or open editor
        };
    </script>
</body>
</html>

Rendering template

Use jsreport.render function to invoke template server side rendering. Function takes a whole template json definition or just a string shortid as a parameter. The output report is opened in a new browser tab by default. This can be overridden by setting the first function parameter to jquery object placeholder.

//render a template into the new tab
jsreport.render({ content: "foo", recipe: "phantom-pdf", engine: "jsrender" });

//render a template into the placeholder
jsreport.render($("#placeholder"), { content: "foo", recipe: "phantom-pdf", engine: "jsrender" });

Opening editor

Use jseport.openEditor function to pop up jsreport designer in the modal. This functions takes a whole template definition or just a string shortid as a parameter. Function returns an even emitter to which you can bind and listen to close or template-change events.

jsreport.openEditor(template
    .on("template-change", function (tmpl) {
        //store changes
        template= tmpl;
    }).on("close", function() {
        //save template to your storage
    });

You can also submit additional options for jsreport extensions like sample data or custom script in the openEditor parameters.

jsreport.openEditor({
    content: "<h1>Hello World</h1>",
    data: {
        dataJson: {
            price: "1234"
        }
    }
});

Where dataJson can be any json object or parse-able json string.

You can also set up a custom script to the report template loading input data for the report preview. Using custom scripts user can even specify desired input data source on its own.

Using jsreport storage

The jsreport designer is by default stateless and doesn't store the template in any storage. It is expected you listen to the emitted events and store the template in your own storage if you want.

To enable storing templates in the jsreport storage just add useStandardStorage option when opening editor:

//open template from jsreport storage
jsreport.openEditor("Z1vT7FHyU", { useStandardStorage: true });

Security

Using embed.js to render or edit templates is possible only when the browser get's access to the jsreport server. Exposing unsecured jsreport server to the public audience doesn't need to be a good idea for the internet applications. In this case you can secure jsreport and keep using embed.js using following approaches.

One option is to use secure jsreport server using authentication and authorization extension to limit access to the jsreport. Anonymous user using embed.js can be then authorized using secure token generated by public-templates extension.

Another options is to create a tunnel forwarding request to jsreport through your application. This hides jsreport behind your security layers and also eliminates cross domain calls. You basically just need to catch and resend requests to jsreport and add serverUrl query parameter to specify where the jsreport web client should route requests back. In other words you create a route in your web server which will proxy jsreport server. Example of such a proxy in asp.net can be found here. Implementing such a tunnel in any other language should not be difficult.