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.
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>
Grails 4 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>
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>
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>
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.
PullReports.init invocation with configuration objectIn 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>
PullReports.init invocation with callback functionIn 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 argumentsThe 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 = '...';
}]);
...
});
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.
The JavaScript configuration object passed to PullReports.init may
have the following properties to initialize the Pull Reports™ Report Creator.
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.
The URL to the WAR into which Pull Reports™
is 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.
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.
An object with the following optional properties.
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.
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 plus any table in
a to-one descendant <relationship> to the base table.
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
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.
The JQuery object that represents the preview results toolbar. Use the object to add custom elements such as new buttons to the toolbar.
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"
},...
]
}
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
}
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> — 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);
}
});
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]);
}
});
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.
AngularJS 1.8
JQuery 3.6
Leaflet 1.7
Bootstrap CSS 3.4 [1]
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.
See the parameter API section for more information on how the creator uses the URL's query string.
[1] The Bootstrap CSS excludes the following components since they are unused by the creator: Navbar, Breadcrumbs, Pagination, Pager, Labels, Badges, Jumbotron, Thumbnails, Progress Bars, Media Items, Wells, Popover and Carousel.