Learn how to add custom code to the HTML head and body elements within Pull Reports™ Ad Hoc reports.
Three Export Report REST API formats, html
,
htmltree
,
and map
return complete HTML documents to be displayed in a web browser. By default, the HTML is undecorated
such that the Pull Reports™ export content fills the entire <body>
element.
Pull Reports™ provides two techniques to decorate the exported HTML with additional HTML content: Servlet includes and SiteMesh.
Configure the inclusion of html
or jsp
content via
export.report.include
-prefixed configuration properties.
The value of these properties is a resource path within the deployed WAR to be include via
RequestDispatcher#include
into one of three places within the HTML DOM:
before the close of the <head>
element
after the start of the <body>
element
before the close of the <body>
element
The export.report.include
-prefixed configuration properties may be specified multiple
times within pullreports.properties
to specify or override behavior for specific formats, HTTP
response codes, <catalog>
s, or <report>
s.
export.report.include
property name structureThe structure of export.report.include
-prefixed configuration property names is:
export.report.include[.html|.htmltree|.map].(head.end|body.start|body.end)[.400|.500][.catalogId][.reportId]
Where (...)
demarcated terms are required and [...]
demarcated terms are optional.
The |
character separates the permitted values for a particular term.
When resolving an inclusion value for a particular report, Pull Reports™ follows these rules to determine precedence:
Properties specified for a particular report via [.catalogId][.reportId]
take
precedence over values specified for a particular catalog via [.catalogId]
which take
precedence over values specified without reference to a catalog or report.
Properties specified for either the html
, htmltree
,
or map
format via [.html|.htmltree|.map]
take precedence over values specified without a format.
In the case of a 400 or 500 HTTP response, properties specified with a
[.400|.500]
status code take precedence over values specified without status.
Simple example:
Here is a simple example which includes a navigation.html
header at the top of all html
, htmltree
, and map
export formats:
export.report.include.body.start=/WEB-INF/content/navigation.html
To override the property for a all <report>
s in <catalog id='my-catalog'>
,
add a second property suffixed with the catalog id:
export.report.include.body.start=/WEB-INF/content/navigation.html export.report.include.body.start.my-catalog=/WEB-INF/content/my-catalog-navigation.html
export.report.include
property name terms[.html|.htmltree|.map]
Specify either the html
, htmltree
, or map
term to apply the property
to the html
, htmltree
, or map
format
respectively. If not specified,
the value of the property applies to all formats.
(head.end|body.start|body.end)
(Required)Specify the inclusion location with the HTML document via one of the three following terms.
head.end: before the close of the <head>
element
body.start: after the start of the <body>
element
body.end: before the close of the <body>
element
[.400|.500]
Specify either the 400
or 500
term to apply the property
to the respective HTML response code. If not specified,
the value of the property applies to all response codes.
[.catalogId][.reportId]
Specify a <catalog>
id
and, optionally, <report>
id
to limit the property to a specific catalog or report.
export.report.include
property examplesThe following example pullreports.properties
contains several
permutations of the export.report.include
-prefixed properties with
explanatory comments.
# Configures default body.start and body.end includes for all responses # of 500 (error) status export.report.include.body.start.500=/WEB-INF/error-header.html export.report.include.body.end.500=/WEB-INF/error-footer.html # Configures default body.start and body.end includes for all responses # of 400 (bad request / validation error) status export.report.include.body.start.400=/WEB-INF/validation-error-header.html export.report.include.body.end.400=/WEB-INF/validation-error-footer.html # Configures default head.end include for all export results of format type # map. The included file might contain CSS or JavaScript code to customize # the map export. export.report.include.map.head.end=/WEB-INF/map-head-include.jsp # Configures default body.start and body.end includes for all responses. # These includes could contain common header navigation and common footer # elements respectively. export.report.include.body.start=/WEB-INF/page-header.jsp export.report.include.body.end=/WEB-INF/page-footer.jsp # Override the includes for <catalog id='my-catalog'>. export.report.include.body.start.my-catalog=/WEB-INF/my-catalog-page-header.jsp export.report.include.body.end.my-catalog=/WEB-INF/my-catalog-page-footer.jsp # Override the 400 head include for the html format for <report id='my-report'> # within <catalog id='my-catalog'>. export.report.include.html.head.end.400.my-catalog.my-report=\ /WEB-INF/validation-error-html-head-include-my-report.html
Follow these steps to decorate the exported HTML with the SiteMesh framework.
Make the SiteMesh JAR available to the web application into which Pull Reports™ is installed
by placing the JAR within the WEB-INF/lib
directory.
If using Gradle dependency management, add the following dependency:
implementation 'org.sitemesh:sitemesh:3.2.1'
Create an extension of org.sitemesh.config.ConfigurableSiteMeshFilter
which excludes the htmltable
format from decoration.
package com.pullreports.examples.sitemesh;
import jakarta.servlet.*;
import org.sitemesh.config.ConfigurableSiteMeshFilter;
import java.io.IOException;
public class ExampleSiteMeshFilter extends ConfigurableSiteMeshFilter {
@Override
public void doFilter(ServletRequest request, ServletResponse response,
FilterChain chain) throws IOException, ServletException {
if ("htmltable".equals(request.getParameter("format"))){
// Excludes the htmltable format from decoration.
chain.doFilter(request, response);
} else {
super.doFilter(request, response, chain);
}
}
}
Install the SiteMesh filter in web.xml
.
<filter> <filter-name>sitemesh</filter-name> <filter-class>com.pullreports.examples.sitemesh.ExampleSitemeshFilter</filter-class> </filter> <filter-mapping> <filter-name>sitemesh</filter-name> <url-pattern>/pullreports/catalog/*</url-pattern> </filter-mapping>
Create a sitemesh3.xml
file within the
WEB-INF
directory with this content:
<?xml version="1.0" encoding="UTF-8"?> <sitemesh> <mapping path="/pullreports/catalog/*" decorator="decorator.jsp"/> </sitemesh>
Create a decorator.jsp
file
within the WEB-INF/decorators
directory and use the SiteMesh
custom tags to apply the decoration.
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>SiteMesh Demonstration</title> <sitemesh:write property="head"/> </head> <body> <h5>Decorated with SiteMesh</h5> <sitemesh:write property="body" /> </body> </html>
After performing these steps, SiteMesh will decorate text/html
responses.
See the SiteMesh documentation for more information about SiteMesh configuration.