The JavaScript API exposed through jrio.js allows you to embed reports into your web pages and web applications. The embedded elements are fully interactive, either through the UI or programmatically. Users navigate their data in the context of your app, and you can dynamically compute, update, or render the jrio.js elements to create seamless interaction. You can use JavaScript frameworks for layout and control the look and feel of all elements through style sheets (CSS).
With the JavaScript API, you can invent new ways to merge data into your application, and make advanced business intelligence available to your users.
This chapter contains the following sections:
| • | Loading the jrio.js Script |
| • | Configuring the JasperReports IO Client |
| • | Usage Patterns |
| • | Testing Your JavaScript |
| • | Changing the Look and Feel |
Each function of the JasperReports IO JavaScript API is then described in the following chapters:
| • | JavaScript API Reference - report |
| • | JavaScript API Reference - Errors |
The last chapters demonstrate more advanced usage of the JasperReports IO JavaScript API:
| • | JavaScript API Usage - Report Events |
| • | JavaScript API Usage - Hyperlinks |
| • | JavaScript API Usage - Interactive Reports |
Loading the jrio.js Script
The script to include on your HTML page is named jrio.js. It is located on your running instance of the JasperReports IO JavaScript API distribution, which is available for download and can be deployed in your hosting web application. Later on your page, you also need a container element to display the report from the script.
...[/code] |
The content of jrio.js is type='text/javascript', but that is the default so you usually don't need to include it.
Configuring the JasperReports IO Client
Loading the jrio.js script as above gives you access to the JasperReports IO JavaScript API in your web page.
But this JasperReports IO client-side API needs to be configured to point to an existing JasperReports IO REST reporting service URL which delivers the actual reports output to be displayed on the current page, the location of the API scripts (either optimized or non-optimized) and UI theme.
This is achieved by calling the config() function on the jrio object made available globally on the page by the loading of the jrio.js script:
jrio.config({ server : "http://bi.example.com:8080/jrio", scripts : "http://bi.example.com:8080/jrio-client/optimized-scripts", theme: { href: "http://bi.example.com:8080/jrio-client/themes/default" }, locale: "en_US"});[/code] |
You can specify several parameters when requesting the script:
| Parameter | Type or Value | Description |
|---|---|---|
| server | URL | The URL to the JasperReports IO service that responds to the report generating REST requests. This parameter is required. |
| scripts | URL | The URL to the folder containing the JasperReports IO JavaScript API files, either in optimized or non-optimized format. This parameter is required. |
| theme | URL | The URL to the folder containing the JasperReports IO JavaScript UI theme files. |
| locale | locale string | Specify the locale to use for display and running reports. It must be one of the locales supported by JasperReports IO. The default is the locale configured on the server. This parameter is required. |
| logEnabled | true|false | Enable or disable logging. By default, it is disabled (false). |
| logLevel | debug|info|warn|error | Set the logging level. By default the level is error. |
| | The server, scripts, and locale parameters are required. The jrio object may produce errors if they are not set. |
The scripts making up the JasperReports IO JavaScript API are available in two formats: optimized and non-optimized. They are placed in separate folders in the JasperReports IO JavaScript API distribution under /optimized-scripts and /scripts subfolders respectively.
If you notice undesirable side-effects when including the JasperReports IO JavaScript library, change the client configuration to use the optimized scripts to provide better protection, also known as encapsulation. For example, the JasperReports IO JavaScript API functions might interfere with collapse functions on your menus. Non-optimized scripts are preferred when you want to perform some runtime debugging for the JavaScript code.
If you want to used the optimized jrio.js script, use the following URL to load it: <script src="http://bi.example.com:8080/myapp/jriojsapi/optimized-scripts/jrio/jrio.js"></script>
If you want to use the non-optimized jrio.js script, you will have to use all of the following scripts:
[/code] |
Usage Patterns
After configuring the JasperReports IO client object, you write the callback that will execute inside this client provided by jrio.js.
Testing Your JavaScript
As you learn to use the JasperReports IO JavaScript API and write the JavaScript that embeds your reports into your web app, you should have a way to run and view the output of your script.
In order to load jrio.js, your HTML page containing your JavaScript must be accessed through a web server. Opening a static file with a web browser does not properly load the iframes needed by the script.
One popular way to view your JasperReports IO output, is to use the jsFiddle online service. You specify your HTML, JavaScript, and optional CSS in 3 separate frames, and the result displays in the fourth frame.
Another way to test your JavaScript is to use the app server bundled with JasperReports IO. If you deploy the server from the installer with the Jetty web application server, you can create an HTML file at the root of one of the web apps shipped with it by default, for example:
<jrio-install>/jrio/webapps/jrio-docs/testscript.html
Write your HTML and JavaScript in this file, and then you can run jrio.js by loading the file through the following URL:
http://mydomain.com:8081/jrio-docs/testscript.html
Changing the Look and Feel
When you create a web application that embeds JasperReports IO content, you determine the look and feel of your app through layout, styles, and CSS (Cascading Style Sheets). Most of the content that you embed consists of reports and dashboards that you create with JasperReports IO or Jaspersoft Studio, where you set the appearance of colors, fonts, and layout to match your intended usage.
But some JasperReports IO JavaScript API elements also contain UI widgets that are generated by the server in a default style, for example the labels, buttons, and selection boxes for the input controls of a report. In general, the default style is meant to be neutral and embeddable in a wide range of visual styles. If the default style of these UI widgets does not match your app, there are two approaches described in the following sections:
| • | Customizing the UI with CSS – You can change the appearance of the UI widgets through CSS in your app. |
| • | Customizing the UI with Themes – You can redefine the default appearance of the UI widgets in themes on the server. |
Customizing the UI with CSS
The UI widgets generated by the server have CSS classes and subclasses, also generated by the server, that you can redefine in your app to change their appearance. To change the appearance of the generated widgets, create CSS rules that you would add to CSS files in your own web app. To avoid the risk of unintended interference with other CSS rules, you should define your CSS rules with both a classname and a selector, for example:
To change the style of specific elements in the server's generated widgets, you can find the corresponding CSS classes and redefine them. To find the CSS classes, write the JavaScript display the UI widgets, for example input controls, then test the page in a browser. Use your browser's code inspector to look at each element of the generated widgets and locate the CSS rules that apply to it. The code inspector shows you the classes and often lets you modify values to preview the look and feel that you want to create.
Customizing the UI with Themes
You can redefine the default appearance of the UI widgets in themes on the server.
Themes are CSS in the JasperReports IO JavaScript API. The UI widgets in JasperReports IO elements are generated on the server and their look and feel is ultimately determined by themes.
Recommended Comments
There are no comments to display.