Adding JavaScript to a report

Add JavaScript to a report to provide your own user interfaces when the report is run in HTML.

About this task

In IBM® Cognos® Analytics, you can add JavaScript in the following ways.

  • As with IBM Cognos Business Intelligence releases, you can add JavaScript in HTML item objects.

    In Cognos Analytics, JavaScript in HTML items is run only when the report is run with limited interactivity (the report property Run with full interactivity is set to No).

    Note: If you run a report with full interactivity, use HTML items to insert only static HTML or static CSS into the report output.
  • You can add JavaScript to reports by using two types of Asynchronous Module Definition (AMD) modules.

    With this choice, JavaScript is run when the report is run with full interactivity (the report property Run with full interactivity is set to Yes).

    The JavaScript must exist in a separate file that your browser can access.

The two types of AMD modules that you can use are

  1. A module that implements the CustomControl Module interface.
  2. A module that implements the Page Module interface.

You add a CustomControl Module interface to a report by referencing the interface in a custom control object. The reference is a file location that you specify in the Module path property of the custom control. Add a custom control to provide your own user interface for a prompt-like control that reads and sets parameters or for page navigation buttons. You can configure the custom control by setting the Configuration property. It allows authors to change parameters without having to go into the JavaScript code itself, make changes, save it, and upload it to the server. One JavaScript file can have multiple uses.

You add a Page Module interface by referencing the interface in a report page or a prompt page. The reference is a file location that you specify in the Module path property of the page. Add a page module to set the initial state of prompt controls, set prompt control custom validation functions, or read current selections from a prompt control.

For information about the JavaScript that Cognos Analytics supports, see Scriptable Reports and JavaScript samples.

Procedure

  1. To add a custom control, from the toolbox toolbox icon under ADVANCED, drag the Custom control icon custom control icon to the report.
    1. To add a data set to the custom control, select the custom control and click the Add data set icon add data set icon in the on-demand toolbar. Drag data items from the Sources tab sources icon into the data set.
    2. Select the custom control and click the Show properties icon show properties icon.
    3. To specify the location of the file that contains the JavaScript that you want to use for the control, click the Module path property.
    4. To add JSON that configures the custom control, click the Configuration property.
      For example, add JSON that sets the orientation, alignment, and background color of the control.
      Note: The JavaScript must be written to accept these configuration elements.
    5. To specify how you want the control to interact with the report, click the UI type property.

      If you do not want to render an interface, set the property to None. If you do not want events, such as mouseup, 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.

  2. To add a page module interface, open the property sheet of the report page or prompt page, click the Module path property, and specify the location of the file that contains the JavaScript that you want to use.