Ad Hoc Report Creator Installation

Abstract

Learn how to embed the Ad Hoc 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™ Ad Hoc Report Creator into an HTML page.

Basic HTML Template

Follow this HTML template to include the required <meta>, <link>, and <script> tags within the <head> element of the web page. The referenced CSS and JavaScript files are included within the Pull Reports™ JAR file and automatically available from 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>

Potential CSS or JavaScript conflicts

The Pull Reports™ Ad Hoc Report Creator CSS and JavaScript files include many additional 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 Ad Hoc Report Creator into a web page with no or minimal additional CSS and JavaScript dependencies.

Pull Reports™ Ad Hoc Report Creator CSS and JavaScript dependencies

Potential anchor (#) and query string (?) conflicts

The Ad Hoc Report Creator tracks the state of the user's interactions via the installation web page URL's anchor component (after the # sign) and query string (after the ? sign). Thus, the installation web page must not depend on neither the anchor nor query string for any other rendering because the creator will overwrite both values.

Note

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

Create the Containing DOM Element

Create an empty HTML block element (e.g. div or section) into which the Pull Reports™ Ad Hoc 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 Ad Hoc 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

To initialize the Ad Hoc Report Creator, use the following template code to call the prMain.init method. This template code uses RequireJS to ensure that the appropriate Pull Reports™ dependencies are loaded and angular.element(document).ready to ensure that the containing DOM element is available. Then, it initializes the Ad Hoc Report Creator via the prMain.init method.

<!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>
    <script>
        require(['pr-require-config'],function(){
            require(['angular','pr-main'], function(angular,prMain) {
                    angular.element(document).ready(function() {
                        prMain.init({
                            container:'pull-reports-container'
                            ,url:'http://localhost:8080/[context]'
                        });
                    });
                }
            );
        });
    </script>
</head>
<body>
    <header>...</header>
    <section data-pr-creator id='pull-reports-container' ></section>
    <footer>...</footer>
</body>
</html>

prMain.init Options

The init method takes a single argument, a JavaScript Object whose property values initialize the Pull Reports™ Ad Hoc Report Creator and returns the creator's AngularJS module object.

The module object may be used for further customization such as setting global HTTP headers

var module = prMain.init({
    ...
});

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

Required options

container

The id of the empty DOM element into which to embed the Ad Hoc 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 Ad Hoc 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.

Restricting the Pull Reports™ Ad Hoc Report Creator to a <catalog>

By default, the Ad Hoc Report Creator's Switch report menu displays a select list of all reports available from the Pull Reports™ installation identified by the url option. Use the following option to restrict the Switch report menu the reports within a single catalog.

catalogId

The id of the <catalog> to which to restrict the available <report> options within the Switch report menu. Use this option to restrict user navigation to reports within one catalog.

Map options

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 panel.

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

Example 1. Example initialization using the Leaflet map options

In this example, 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.

<script>
    require(['pr-require-config'],function(){
        require(['angular','pr-main','leaflet']
            , function(angular,prMain,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
                });
    
                angular.element(document).ready(function() {
                    prMain.init({
                        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);
                }
            }
        );
    });
</script>