The interactive report viewer can render reports with JavaScript embedded starting Cognos Analytics 11 R4. We’ve taken a different approach with the interactive viewer JavaScript support - the JavaScript that you want to add to a report must exist in a separate file that your web browser can access. This allows the same JavaScript to be shared and reused among many reports. For example, if you have a custom prompt control, you can code it once and reference it anywhere in any report by using a new object called Custom control.
How does it work?JavaScript can be added to reports by using the following two types of Asynchronous Module Definition
(AMD) modules.
- A module that implements the CustomControl Module interface.
- A module that implements the Page Module interface.
Examples for when you will want to use a Custom Control
- To provide your own user interface for a prompt-like control that reads and sets parameters.
- To provide your own user interface for page navigation buttons (Next, Finish,...).
- Any type of custom interface or behavior for a supported report object.
To use a Custom Control, drag the ‘Custom control’ icon from the toolbox to the report. Under ‘properties’ of custom control, specify the location of the file that contains the JavaScript you want to use as ‘Module path’.
You can also use the ‘Configuration’ property to pass different parameters to the JavaScript functions accepting them.
The UI type property defines how custom control interacts with the report.
If you do not want to render an interface, set the property to None. If you do not want events, such as mouse up, to propagate from the control to the report, set the property to UI without event propagation. If you want events to propagate to the report, set the property to UI with event propagation.
Examples for when you will want to use a Page Module
- To set the initial state of prompt controls
- To set prompt control custom validation functions
- To read current selections from a prompt control (possibly to store) before going to the next page
- Code (using HTML Item) from a previous release that was executed globally on the page will likely move into the "load" method
- Page module can be used on page objects such as report page or prompt page. ‘Module path’ property is available for page objects when selected.
Examples for when you will want to use an HTML Item
- To insert static HTML into the output
- To insert static CSS into the output
Where to store JavaScript files?JavaScript files can be stored anywhere a browser has access to. For example, you can host JavaScript files on your webserver, or you can include JavaScript files under Cognos install, under webcontent/bi directory. We use RequireJS to load JavaScript files. RequireJS assumes by default that all dependencies are scripts, so .js extension is not required as part of the module path. Example module path (../samples/expandJavaScript). However, there may be times when you do want to reference a script directly. If the path starts with a "/", or if the path contains an URL protocol, like "http:" or "https:", .js should be added to the path. Example module path (http://servername/cognos/samples/expandJavaScript.js)
Report objects supported
- Existing Prompt API (Value prompt, Select & search prompt, Date prompt, Date & time prompt, Time prompt, Interval prompt, Tree prompt and Text box prompt)
- Visualization (3-D combination chart, 3-D scatter chart, Bubble Chart, Bullet chart, Combination chart, Gauge chart, Marimekko chart, Metrics range chart, Pareto chart, Pie chart, Polar chart, Progressive chart, Radar chart, Scatter chart, Win-loss chart)
Why should I use the new JavaScript API?
- It uses the industry standard module loader RequireJS.
- Script files can be dynamically downloaded and cached by both the viewer and the browser's cache.
- With modules, it's possible to reuse script such as a common control in multiple reports instead of copying and pasting HTML items.
- The script is more reusable through parameterization using the Configuration property and passing in data using Data Stores.
- It uses a supported method of accessing IBM data using Data Stores instead of being forced to scrape the HTML output.
- Script files can be edited in your favorite dev tools instead of the HTML Item textbox.
- No global variables
- Multiple instances can exist on a page without using "_THIS_"
- Code does not accumulate and use more and more memory
- It allows you to bring in 3rd party libraries.
- It’s easier to debug
- You can debug just your file without the viewer's implementation getting in the way
- The script author can report an error by throwing a scriptableReportError and the viewer will display the message.
- Scripts written against the supported interfaces will continue to work between releases.
- The API will expand from release to release exposing more capabilities. We welcome customer feedback through RFE community voting.
- Events/notifications are provided for proper synchronization.
- It expands the original Prompt API and exposes most controls for scripting
- Many extensions points provided to seamlessly implement an alternative prompt control
- All controls can be accessed by name in addition to prompt controls.
- Simpler to implement collapsible regions
What happens to existing reports with JavaScript embedded via HTML itemInline JavaScript and referencing external script using HTML items will continue to work when report is rendered in classic viewer (with Full Interactivity set to No). This does not include JavaScript written specifically for rendering in quirks mode, or JavaScript relies on our DOM (Document Object Model) structure.
Detailed
technical documentation describes the new APIs can be found here.
SamplesThere is a new set of samples for Scriptable Reports for 11.0.5. These samples are installed by default in an Easy installation, and are an option in a Custom installation. You can find them here:
<Cognos installation directory>\samples\JavaScript\For your convenience, you can also obtain the samples here. Download the following three files:
1. Follow these
setup instructions.
If you are using a Gateway, please read Step 6 carefully!2. Unzip and place these
javascript files.
3. Import this report
deployment.
Related posts:
#11.0.4#11.0.5#11.0.6#Administration#authoring#classicviewer#CognosAnalytics#CognosAnalyticswithWatson#home#JavaScript#LearnCognosAnalytics#reporting#Scriptablereport