Enhanced Linking in Pentaho-Reporting
The reporting engine allows to place hyperlinks into many of the available output formats (PDF, HTML, Excel). All of these formats use URLs to specify the target document and to pass parameters to this document. However, at the moment, creating these links is a manual process and thus error prone and requires a rather technical skill-set as most links need to incorporate data from the current report-state (and thus must be computed somehow).
The drill-linking extension provides a way to specify the link target and its parameter in a declarative way. This way, the drill-link definition can be well-defined while at the same time its result can be computed.
The drill-link backend (pentaho-reporting-engine-extensions-drill-down)
The link-computation is performed by a single formula function called "DRILLDOWN".
DRILLDOWN
Summary: Computes a drill-down link as text.
Syntax: DRILLDOWN (Text profileName; Text solution; Text reportPath; Text reportId; Array parameter )
Returns: TEXT
Constraints: Parameter-array is a 2x2 array with name value pairs.
{{ "ParamName1" | "ParamValue1" } | { "ParamName2" | " ParamValue2" }}
Semantics: The actual work is done by the profile implementation in the background. Right now, there are two implementations, a simple pattern (message-format) profile and a formula based profile. The profile must be defined in the meta-data. Whether value of solution, reportPath and ReportId is actually used depends on the configuration of the profile given. The parameter array must be given, even if it is empty. Each profile is defined to compute a URL or to throw an Evaluation-Error if some of the values are illegal.
By encapsulating the drill-down parameters into a formula function, we abstract the actual target of the link from the report-definition. When migrating a report from one system to another, the report-definition can remain unchanged and still pick up changes in the URL configuration.
The drill-down system ships with 4 profiles at the moment. The examples provided here show both the DRILLDOWN formula that will be generated by the UI as well as the underlying drill-down-profile defined by an administrator.
generic-url: a link to a third-party web-page on a server located somewhere remote. Report-Path and the parameter-values are used. Report-Path specifies the full URL, and parameters specify the parameter you want to pass.
DRILLDOWN ("generic-url"; ""; "http://www.google.com/?"; ""; {{"q", "your-query"}})
<drilldown-profile name="generic-url"
class="org.pentaho.reporting.engine.classic.extensions.drilldown.PatternLinkCustomizer"
bundle-name="org.pentaho.reporting.engine.classic.extensions.drilldown.drilldown-profile"
expert="true" hidden="true" preferred="false" deprecated="false">
<attribute name="pattern">${1}${3}</attribute>
<attribute name="extension">xaction</attribute>
<attribute name="parameter-encoding">urlencode</attribute>
</drilldown-profile>
local-url: a link to a web-page on the same server. Report-Path and the parameter-values are used. Report-path specifies the local path relative to the "serverBaseURL".
DRILLDOWN ("local-url"; ""; "/mywebapp/myownservlet?"; ""; {{"param", "your-value"}})
<drilldown-profile name="local-url"
class="org.pentaho.reporting.engine.classic.extensions.drilldown.PatternLinkCustomizer"
bundle-name="org.pentaho.reporting.engine.classic.extensions.drilldown.drilldown-profile"
expert="true" hidden="true" preferred="false" deprecated="false">
<attribute name="formula">ENV("serverBaseURL")${1}${3}</attribute>
<attribute name="extension">xaction</attribute>
<attribute name="parameter-encoding">urlencode</attribute>
</drilldown-profile>
local-xaction: A link to a xaction running on the same server and the same web-application. All parameter are used and inserted into the final URL.
DRILLDOWN ("local-xaction"; "steel-wheels"; "test/dir"; "sample.xaction"; {{"param", "your-value"}})
<drilldown-profile name="local-xaction"
class="org.pentaho.reporting.engine.classic.extensions.drilldown.PatternLinkCustomizer"
bundle-name="org.pentaho.reporting.engine.classic.extensions.drilldown.drilldown-profile"
expert="true" hidden="true" preferred="false" deprecated="false">
<attribute name="formula">ENV("pentahoBaseURL") & "viewaction?solution=" & URLENCODE(\["::solution"\]) & "&path=" & URLENCODE(\["::reportPath"\]) & "&name=" &URLENCODE (\["::reportId"\]) & "&" \["::parameter"\]</attribute>
<attribute name="extension">xaction</attribute>
<attribute name="parameter-encoding">urlencode</attribute>
</drilldown-profile>
local-prpt: A link to a local PRPT with the parameter UI shown.
DRILLDOWN ("local-prpt"; "steel-wheels"; "test/dir"; "sample.prpt"; {{"param", "your-value"}})
<drilldown-profile name="local-prpt"
class="org.pentaho.reporting.engine.classic.extensions.drilldown.PatternLinkCustomizer"
bundle-name="org.pentaho.reporting.engine.classic.extensions.drilldown.drilldown-profile"
expert="true" hidden="true" preferred="false" deprecated="false">
<attribute name="formula">ENV("pentahoBaseURL") & "content/reporting/reportviewer/report.html?solution=" & URLENCODE(\["::solution"\]) & "&path=" & URLENCODE(\["::reportPath"\]) & "&name=" &URLENCODE (\["::reportId"\]) & "&" \["::parameter"\]</attribute>
<attribute name="extension">prpt</attribute>
<attribute name="parameter-encoding">paramvalue</attribute>
</drilldown-profile>
The drill-down profiles can be queried at runtime via the DrillDownProfileMetaData-API and can provide design-time hints to the UI, similar to the Metadata-API for Elements and Expressions.
Drill-Down UI
The drill-down UI is a specialized editor for the DRILLDOWN function. The editor is only expected to work with a pure DRILLDOWN function without any additional formula functionality around it. If a user embeds the DRILLDOWN function into his own larger formula, then he will have to use the plain formula-editor to configure it.
I do expect that our users create their own profiles. The backend is flexible enough to accommodate any URL format. Ideally, the editor for a given profile should be configurable as a plugin by letting the user provide his own Xul-overlay and Xul-Controller.
Drill-Down profiles pointing to services provided by Pentaho will deliver a list of available parameter to the UI. The parameter-list will contain both the system-level parameter (for "local-prpt", for instance, the system parameter list will contain all defined parameter of the reporting plugin) along with the user-defined parameter.
Drill-Down profiles pointing to external services must be able to define parameters manually.
Parameter-Names and Parameter-Values can either be static (hard coded) values or values computed at runtime (any formula term, function or field-reference will work).
If the editor encounters an undefined profile, it has to default to a generic editor, so that the user can edit or correct the definition. (I do expect to see many undefined profiles in reports sent to support, as we are generally not in possession of the user's drill-down profile definitions.)
Drilling into a new Window
use the following javascript URL:
javascript:top.reportViewer_openUrlInDialog('title', 'http://www.pentaho.com/','800px', '600px')
This only works if the report is run in the platform.
Drilling into a new Tab
To open a report in a new tab within the platform use the following formula function:
=OPENINMANTLETAB([url]; [tab-text])
This creates the following javascript-url:
javascript:top.mantle_openTab('<contents of tab-text>', '<contents of tab-text>', '<contents of url reference>')