The Pentaho Prompting API was introduced in Pentaho Common UI version 1.0.2 and is included in the BI Server 4.5+.
The source is part of the Pentaho Common UI project and can be found here:
A simple working example is provided as part of the Pentaho Prompting project in a running BI Server:
You can use this page to experiment with different settings by manipulating the parameter xml that drives the prompt.
The following modules exist in Pentaho Prompting API:
|common-ui/prompting/pentaho-prompting||Main Pentaho Prompting APIs: PromptPanel, ParameterXmlParser, ParameterDefinition and associated objects (ParameterGroup, Parameter, ParameterValue, ..)|
|common-ui/prompting/pentaho-prompting-builders||Widget Builder API and implementations for the standard components|
|common-ui/prompting/pentaho-prompting-components||Widget component implementations|
The API is fairly straight forward. Given xmlString, the parameter xml, we're able to parse it into a parameter definition using the included parameter xml parser:
The core of Pentaho Prompting is the panel that contains all the UI components that allow a user to interact with it. The layout is controlled by a pentaho.common.prompting.ParameterDefinition. The Parameter XML Specification component types are mapped to Pentaho CDF components defined in the CDF project itself, the prompting project, or any custom components. A parameter is mapped to a CDF component by it's "type" attribute. The pentaho.common.prompting.builders.WidgetBuilder is responsible for mapping and building components for a given parameter type.
To create a prompt panel from a parameter definition you can use the following code:
The following methods can be overridden to customize the prompt panel:
- submit = function() called when auto-submit is triggered or the user manually triggers the submit button.
- schedule = function(): called when the schedule button is triggered.
- getParameterDefinition = function(paramPanel, callback): This is provided as a way to dynamically update the parameter definition based on new input. This allows for the implementation of cascading parameters. It is called whenever a parameter's value changes. The paramPanel argument is the panel which is being updated and the callback is the refresh function which should be called with the updated parameter definition to refresh the prompt panel.
- createDataTransportFormatter = function(paramDefn, parameter, pattern, formatter): This should return an object capable of formatting an object to the format used to send over the wire (the format it is transported in).
- getString = function(key, defaultString): Used for i18n. The default implementation always returns the default string. Override to provide custom i18n support.
The Pentaho Prompting UI relies on a set of builders to create all the components that make up the prompt. From the panels that lay out the components to the input components themselves. All of this is funneled through pentaho.common.prompting.builders.WidgetBuilder. The builder is responsible for creating an object that represents a Dashboards component.
The most simple CDF component can be described as an object with an update() function. When Dashboards initializes, and on every refresh, it calls update() on all its components.
Here's a simple component that appends " (My Custom Component)" to all labels of a prompt.
*Note: this.htmlObject is by convention the ID of the element where the component should be injected.
For this example let's say we want to replace the default label component used to describe all prompt labels with our custom component. In order to do so we'll override the existing builder for our label component type and generate objects that describe our new custom component. Dashboards will take care of turning these metadata objects into the actual components.
WidgetBuilder.build(args, typeOverride) should create a metadata object describing a component. The typeOverride allows for the component type to be explicitly specified. If not, the args.param.attributes["parameter-render-type"] value is used to look up a builder in the WidgetBuilder.mapping map which should be capable of creating a metadata object describing a component of the desired type.
The args argument to WidgetBuilder.build(args, typeOverride) is a hash of key/value pairs providing hints and information for the builder. Common key/values that you can expect to exist for any call to build() are:
- promptPanel: the prompt panel this component is being built for
- param: the parameter this component is being built for
Finally, here's an example of a custom builder to create a MySimpleComponent (as defined above) for all components of type 'label':
Sample components are registered via the plugin's plugin.xml as external resources. A working sample component can be found here:
And it is registered through Common UI's plugin.xml here (found in the common-ui/ plugin directory in a working installation):
Pentaho Prompting was created to serve as a basis for the Pentaho Reporting Web Viewer. The Pentaho Reporting Engine requires parameters to adhere to a specific format. To bridge the gap between CDF component's internal formats and what the reporting engine expects we must format values into at least 2 different formats: wire format and display format.
The source is located in the Pentaho GWT Widgets project:
The GWT module is available in a Pentaho BI Server in the Pentaho Common UI project:
There are two methods defined for a formatter: parse and format that are analogous to the similarly named methods defined for java.text.Format.