Report Creator Installation

Abstract

Learn how to embed the Report Creator into any web page in order to add ad hoc reporting and data service capability to any web application.


Follow these steps to embed the Pull Reports™ Report Creator into a web page.

Basic Installation

HTML <head> Elements

Use the HTML template below to include the required <meta>, <link>, and <script> tags within the <head> element of the installation web page. The referenced CSS and JavaScript files are included within the Pull Reports™ JAR file and automatically available from the context path of the WAR serving Pull Reports™.

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="/[context]/assets/pullreports.min.css">
    <script src="/[context]/assets/pullreports.min.js"></script>
</head>
<body>
...
</body>
</html>

Important note for Grails 3

Grails 3 serves static content from JAR META-INF/resources directories beneath the /static URL path. For this reason, prefix all paths to Pull Reports.css and .js files with /static.

<link rel="stylesheet" href="/[context]/static/assets/pullreports.min.css">
<script src="/[context]/static/assets/pullreports.min.js"></script>

Using non-minified CSS and JavaScript

To use non-minified CSS or JavaScript files for easier debugging, reference the non-minified versions like so:

<link rel="stylesheet" href="/[context]/assets/pullreports.css">
<script src="/[context]/assets/pullreports.js"></script>

Containing DOM Element

Create an empty HTML block element (e.g. div or section) into which the Pull Reports™ Report Creator will install. This element should be attributed with a unique id attribute and must contain the required data-pr-creator attribute. The element is typically located within the main content section of the web page. For the best experience when using the Report Creator, the element should span 100% of the screen width.

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="/[context]/assets/pullreports.min.css">
    <script src="/[context]/assets/pullreports.min.js"></script>
</head>
<body>
    <header>...</header>
    <section data-pr-creator id='pull-reports-container'></section>
    <footer>...</footer>
</body>
</html>

JavaScript Initialization

The pullreports.min.js file adds the PullReports object as a global JavaScript variable. Call the PullReports.init method to initialize the Report Creator within the containing DOM element. PullReports.init requires a single argument: either a JavaScript object whose properties configure the creator or a callback function which returns the JavaScript configuration object.

PullReports.init must be called after the Pull Reports™ dependencies are loaded and the containing DOM element is available. To accomplish this, the following examples put the initialization <script> tag just before the end of the HTML <body>, but PullReports.init could also be invoked within a DOMContentLoaded event handler.

Example 1. Example PullReports.init invocation with configuration object

In the following example, PullReports.init is called with a JavaScript configuration object as the single argument. The properties of the object will be used to initialize the Report Creator. See the initialization property reference below for a description of each property.

<!doctype html>
<html lang="en">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="/[context]/assets/pullreports.min.css">
    <script src="/[context]/assets/pullreports.min.js"></script>
</head>
<body>
    <header>...</header>
    <section data-pr-creator id='pull-reports-container' ></section>
    <footer>...</footer>
    <script>
        PullReports.init({
            url:"http://localhost:8080/[context]"
            ,container:"pull-reports-container"
        });
    </script>
</body>
</html>

Example 2. Example PullReports.init invocation with callback function

In the following example, PullReports.init is called with a callback function as the single argument. The callback function must return a JavaScript object which will be used to initialize the Report Creator. See the initialization property reference below for a description of each property.

<!doctype html>
<html lang="en">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="/[context]/assets/pullreports.min.css">
    <script src="/[context]/assets/pullreports.min.js"></script>
</head>
<body>
    <header>...</header>
    <section data-pr-creator id='pull-reports-container' ></section>
    <footer>...</footer>
    <script>
        PullReports.init(function(module,L){
            return {
                url:"http://localhost:8080/[context]"
                ,container:"pull-reports-container"
            };
        });
    </script>
</body>
</html>

When passing a callback function as the single argument to PullReports.init, the callback function receives the following arguments in order. These arguments may be used to customize the returned JavaScript configuration object.

PullReports.init callback function arguments

module

The creator's AngularJS module object. Use the module object for further AngularJS customization such as setting global HTTP headers.

For example, the following initialization code sets a custom Authorization header for every creator HTTP request.

PullReports.init(function(module,L){
    module.run(['$http',function($http) {
        $http.defaults.headers.common.Authorization = '...';
    }]);
    ...
});
L

The Leaflet object used to create the preview map for reports which support the geojson export report format. When used in conjunction with the map initialization property, the Leaflet object may be used to add additional controls to the preview map.


Initialization Properties

The JavaScript configuration object passed to PullReports.init may have the following properties to initialize the Pull Reports™ Report Creator.

Required Properties

container

The id of the empty DOM element into which to embed the Report Creator. The element is typically is a <div> or <section> element. The element must have the data-pr-creator attribute.

url

The URL to the WAR into which Pull Reportsis installed. The Report Creator will append /pullreports/... to this URL to invoke the Pull Reports REST API.

Since the creator will initiate AJAX requests to this url, ensure that the creator is embedded in a web page served from the same domain as the Pull Reports™ WAR or access to the Pull Reports™ WAR is permitted via appropriate Access-Control-Allow-Origin headers.

Map View Mode Properties

For those Pull Reports™ which declare a <geojson> element, the map option allows control over the behavior of the embedded Leaflet map on the results preview.

See Example 3, “Example initialization using the Leaflet map options” for an example usage of the map property.

map

An object with the following optional properties.

initCallback

A JavaScript function to be invoked after map initialization. The arguments to the function are:

  • map: The Leaflet map.

  • geoJsonLayer: The Leaflet markercluster layer which contains the GeoJSON Layer which in turn contains the GeoJSON result of the Export REST API, geojson format.

geoJsonOptions

A JavaScript object to be passed to the Leaflet GeoJSON layer upon construction. See the Leaflet GeoJSON documentation for a complete list of configuration options.

If not specified, Pull Reports™ will set the following default GeoJSON layer option values:

  • onEachFeature: Set to a function which binds a Leaflet popup to the layer for each feature. The content of the popup is a two column table of GeoJSON feature property names to values. The property names and values are the exported <column>s of the report's base table.

options

A JavaScript object to be passed to the Leaflet map upon construction. See the Leaflet map options documentation for a complete list of configuration options.

If not specified, Pull Reports™ will set the following default map option values:

  • center: Set to the geographic center of the lower 48 United States.

  • layers: Set to an array with a single Open Street Map base layer.

  • zoom: Set to 4

Additional Properties

creatorControlsCallback

A callback function which is invoked after the Report Creator preview results toolbar is added to the HTML DOM. Use the callback function to add custom controls to the toolbar.

See Example 4, “Example initialization which adds a custom results preview toolbar button” for an example usage of the creatorControlsCallback property.

The creatorControlsCallback callback function receives the following two parameters.

$element

The JQuery object that represents the preview results toolbar. Use the object to add custom elements such as new buttons to the toolbar.

exportReportConfigProvider

A JavaScript function that when invoked returns an Object representation of the current results preview Export Report REST API request. The Object has the following properties:

{
  reportId: string
  catalogId: string,
  distinct: boolean,
  columns: [
    {
      tablePath: string,
      columnId: string
    },...
  ],
  filters: [
    {
      source: string
      terms: [
        {
          tablePath: string,
          columnId: string,
          operator: string,
          values: [...]
        },...
      ]
    },...
  ],
  sorts: [
    {
      tablePath: string,
      columnId: string,
      direction: "asc"|"desc"
    },...
  ]
}
adHocCreatorParams

The optional adHocCreatorParams property is a JavaScript object whose properties mirror the catalogId, reportId, columns, filter, sort, and distinct parameters of the Creator Parameter API. When the adHocCreatorParams initialization property is defined, the creator will open to the Ad Hoc Report Creator pre-configured with the respective parameters.

Use the adHocCreatorParams initialization property as an complimentary way to open to the Ad Hoc Report Creator to a specific Export Report REST API configuration similar to the Creator Parameter API. Additionally, note that the presence of the adHocCreatorParams initialization property will override any Creator Parameter API values defined within the browser's location.

The adHocCreatorParams Object has the following properties:

{
  // Required. The <report> id
  reportId: string
  // Required. The <catalog> id
  catalogId: string,
  // Optional. The Export Report API "distinct" parameter
  distinct: boolean,
  // Optional. The Export Report API "columns" parameter
  columns: string, 
  // Optional. An array in which each member is an Export Report API "filter" parameter.
  filter: [string], 
  // Optional. The Export Report API "sort" parameter
  sort: string, 
  // Optional. Either "map" or "table". The default is "table". 
  // Determines the initial view mode of the Ad Hoc Creator Results Preview.
  // "map" viewMode is only applicable for <report>s which support the "geojson" format.
  viewMode: string
}

Advanced Examples

Example 3. Example initialization using the Leaflet map options

This example uses the PullReports.init callback function technique to create custom controls on the Report Creator preview map with the aid of the Leaflet callback function argument. Using the Leaflet object, two base layers are created, 'MapQuest Open Aerial' and 'Open Street 'Map'. 'Open Street Map' is set as the default base layer via the options.layers property. Additionally, both base layers are added to a Leaflet Layers control as toggleable base layers while the exported GeoJSON layer is labeled 'Student residences' and also made toggleable.

PullReports.init(function(module,L){

    // Create two base layers
    var baseLayers = [];
    baseLayers['MapQuest Open Aerial'] = 
        L.tileLayer('http://otile{s}.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.{ext}', {
        type: 'sat',
        ext: 'jpg',
        attribution: 'Tiles Courtesy of <a href="http://www.mapquest.com/">MapQuest</a> &mdash; Portions Courtesy NASA/JPL-Caltech and U.S. Depart. of Agriculture, Farm Service Agency',
        subdomains: '1234'
        ,maxZoom: 18
    });
    baseLayers['Open Street Map'] = 
        L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
        attribution: 'Map data © <a href="http://openstreetmap.org">OpenStreetMap</a> contributors'
        ,maxZoom: 18
    });

    return {
        container:"report-container"
        ,url:'https://www.example.domain.com/'
        ,map: {
            options: {
                // Set the default (lowest) layer to be 'Open Street Map'
                layers:[baseLayers['Open Street Map']]
            }
            ,initCallback:initializeMap
            ,geoJsonOptions: {
                // Customize the Leaflet popup.
                onEachFeature:function(feature,layer){
                    layer.bindPopup(function(){
                        return '<h3>' + feature.properties['Some Property'] + '</h3>';
                    });
                } 
                // Customize the GeoJSON style
                ,style:{"color": "#FA8072",
                    "weight": 5,
                    "opacity": 0.8
                }
            }
        }
    };

    function initializeMap(map,geoJsonLayer){
        // Initialize a Leaflet layers control with the two base layers plus
        // the report's geojson layer. The layer's control will allow users to 
        // toggle the base layers and turn on/off the visibility of the geojson layer. 
        L.control.layers(baseLayers, {'Student residences':geoJsonLayer}).addTo(map);
    }
});

Example 4. Example initialization which adds a custom results preview toolbar button

In this example, a custom "Click Me" button is added to the results panel toolbar just before the "Export" button. Clicking the button prints the current state of the export report parameters to the JavaScript console.

PullReports.init({
    url:"/"
    ,container:"report-container"
    ,creatorControlsCallback: function($element,exportReportConfigProvider){
        var div = document.createElement('div');
        div.className = 'pr-preview-control-group';
        var button = document.createElement('button');
        button.className = 'btn btn-default btn-sm';
        button.style.display = 'block';
        button.innerHTML = 'Click Me';
        button.onclick = function(e){
            var exportReportConfig = exportReportConfigProvider();
            console.log(JSON.stringify(exportReportConfig,null,2));
        }
        div.appendChild(button);
        $element[0].insertBefore(div,$element.find('.pr-export-container')[0]);
    }
});

Potential Conflicts

CSS and JavaScript Conflicts

The Pull Reports™ Report Creator CSS and JavaScript files include library dependencies that may conflict with other CSS and JavaScript dependencies within the embedded web page. The dependencies are listed here to help diagnose problems related to CSS or JavaScript collisions. Because of such conflicts, it is recommended to embed the Report Creator into a web page with no or minimal additional CSS and JavaScript dependencies.

Pull Reports™ Report Creator CSS and JavaScript dependencies

Query String (?) Conflicts

The Report Creator tracks the state of the user's interactions within the installation web page URL's query string. For this reason the installation web page must not depend on the query string for any other rendering because the creator will overwrite the value.

Note

See the parameter API section for more information on how the creator uses the URL's query string.