Some basic techniques for JavaScript Programming of Cognos Prompts

1 Disclaimer.............................................................................................................................2 2 Introduction...........................................................................................................................3 3 JavaScript Usage for Cognos Prompts.................................................................................3 4 Retrieving prompts................................................................................................................4 4.1 Standard prompts...............................................................................................4 4.2 Other prompts....................................................................................................4 5 Common Actions on Prompts ..............................................................................................5 5.1 Modifying the prompts before the prompt page is displayed...........................5 5.1.1 Set a value for a text box............................................................................5 5.1.2 Select an item in a multiselect List Box.....................................................5 5.1.3 Remove the first 2 lines from a Drop Down List prompt..........................5 5.1.4 Enable the Finish button.........................................................................6 5.2 Running scripts after the user clicks the Finish button.....................................7 6 Debugging JavaScript...........................................................................................................9 6.1 Detecting JavaScript errors in Internet Explorer (IE).......................................9 6.2 Using Firebug debugger in Firefox...................................................................9 7 References.............................................................................................................................9 7.1 Upgrading JavaScript Applications to IBM Cognos 8.3/8.4............................9 ..............................................................................................................................................9

1 Disclaimer
The techniques in this document depend on undocumented and unsupported aspects of the Cognos 8 Business Intelligence Cognos 8 Viewer (AKA Report Viewer). These techniques operate in Cognos 8 Viewer only and as such do not operate in any other Cognos 8 BI user interfaces such as Go! Mobile, Go! Dashboards, Query Studio, Analysis Studio, Cognos Analysis for Excel, Go!Office and so on. While IBM will strive to provide compatibility from release to release of Cognos 8 Viewer, all support and compatibility issues are the responsibility of the user and not IBM. Therefore, the use of the techniques comes with the risk of partial or complete incompatibility with the possibility of necessitating a partial or complete change or loss of functionality from release to release. Such risk is borne entirely by the user of these techniques. See also the disclaimer of the document referred in 7.1.

2 Introduction
This document attempts to consolidate and simplify some basic techniques of using JavaScript for Cognos Prompts. JavaScript is used to extend the prompt functionality. The Cognos API for JavaScript prompts has been upgraded from Cognos 8.2 to Cognos 8.3. A reference can be found in section 7.1below. The JavaScript code in this document presents by default the Cognos 8.3 version. Notes have been added where the code is different in Cognos 8.2.

3 JavaScript Usage for Cognos Prompts

JavaScript is used to do some actions on prompts: 1. 2. 3. Modify the prompts before presenting the prompt page to the user Validate user actions Process the prompts after the user presses Finish

The JavaScript must be placed in one or more HTML items in the prompt page. The HTML item must be placed after the prompts it refers to. The JavaScript should be surrounded by <script> and </script> tags. The HTML item may also contain definitions of buttons or other HTML areas.

4 Retrieving prompts
To retrieve a prompt, first get the object containing the whole form.
var form = getFormWarpRequest();

Note 1: the use of getFormWarpRequest() is not fragment-safe. Note 2: in 8.2 the code is:
var form = document.forms["formWarpRequest"];

4.1 Standard prompts

The standard prompts objects can be accessed as properties of the formWarpRequest object, with the following naming conventions: Text Edit Box List Box Drop Down List Radio Button Group Check Box Group Date Edit Box
_textEditBox<prompt name> _oLstChoices<prompt name> _oLstChoices<prompt name> _oLstChoices<prompt name> _oLstChoices<prompt name> txtDate<prompt name>

Example: to get the listBox prompt which has been named XYX, the code is:
var form = getFormWarpRequest(); var listB = form._oLstChoicesXYZ;

4.2 Other prompts

All other prompt objects can be accessed by adding a named span tag <span> around the prompt object and accessing the span tag via the getElementById() function and the prompt object items using the getElementsByTagName() function. See details in the reference 7.1below.

5 Common Actions on Prompts

5.1 Modifying the prompts before the prompt page is displayed
To modify a prompt, create a HTML item, and write a script to retrieve the prompt and set a value for the prompt. In the following examples, the prompt has the name XYZ.

5.1.1 text box

Create a Text Box Prompt and a HTML item containing:
var form = getFormWarpRequest(); var textB = form._textEditBoxXYZ; textB.value="First value"; canSubmitPrompt();

Set a value for a

See also Technotes 1370539 and 1339524.

5.1.2 multiselect List Box

Select an item in a

Create a Value Prompt, and change the Multi-Select property to Yes. This example selects the third value in the list.
var form = getFormWarpRequest(); var listB = form._oLstChoicesXYZ; listB.options[2].selected=true; canSubmitPrompt();

See also Technotes 1371328 and 1342809.

5.1.3 lines from a Drop Down List prompt

Remove the first 2

Create a Value Prompt. By default, the Select UI attribute is DropDownList. The first line contains the parameter name, the second line contains dashes and the actual data starts only on the third line. Some customers want to remove the first two lines:
var form = getFormWarpRequest(); var dropDownL = form._oLstChoicesXYZ; dropDownL.remove(1); dropDownL.remove(0); dropDownL.removeAttribute("hasLabel"); canSubmitPrompt();

// needed only in Cognos 8.3/8.4

See also Technote 1342899.

5.1.4 Finish button

Enable the

In a page containing some required prompts, the Finish button is enabled only when the user has selected values for all the required prompts. The current section shows examples when the prompts are initialized by script. If all the required prompts are satisfied, then the Finish button may be set to enabled, by calling the function:
canSubmitPrompt()

Example: a prompt page contains two prompts: 1. a Text Box Prompt, named ABC, which should be initialized with the string Hello; 2. a Value Prompt of the type ListBox, named DEF, where the first item should be selected. After that, the Finish button should be set to Enabled.
var form = getFormWarpRequest(); var textB = form._textEditBoxABC; textB.value = "Hello"; var listB = form._oLstChoicesDEF; listB.options[0].selected=true; canSubmitPrompt();

Note 1: all the required prompts must be satisfied before calling canSubmitPrompt(). Otherwise the following error message is displayed: One or more of the required values is missing. Required values are needed to produce the report. Note 2: canSubmitPrompt() has been introduced in Cognos 8.3. It checks all the prompts in the page. In Cognos 8.2 the same operation was done by the function checkData(), applied for each prompt. The function checkData() applies to specific variables for each prompt. Such a variable has a name as in the following list, followed by the prompt name:
checkBoxGroup clockDisplay intervalControl listBox pickerControl radioGroup search selectDate selectDateTime selectInterval

selectTime textBox timePicker

The same example, now written in Cognos 8.2 will be:

var form = document.forms["formWarpRequest"]; var textB = form._textEditBoxABC; textB.value="Hello"; var listB = form._oLstChoicesDEF; listB.options[0].selected=true; textBoxABC.checkdata(); listBoxDEF.checkdata();

Note 3: checkData() is still available in Cognos 8.3/8.4.

5.2 Running scripts after the user clicks the Finish button
By default, pressing the Finish button will execute the report with the given prompts. In order to execute additional operations after the user presses the Finish button, but before the report runs, replace the Finish button with a customized one, as follows: Define a JavaScript function to do the expected actions Define a new button to launch the function above Remove the original Finish button Example: a prompt page contains a list and a text box. When Finish is pressed, the text box is filled with the selected option. The prompt page should have: the list prompt the text prompt a HTML item next to the Finish button, containing:
<input type="BUTTON" class="clsPromptButton" onClick="fillTextBox()" value="Finish">

a HTML item containing the requested function, followed by the promptButtonFinish() call, which will perform the Finish button action.
<script> function fillTextBox() { var form = getFormWarpRequest(); var list = form._oLstChoicesABC; var textBox = form._textEditBoxXYZ; for (i = 0; i < list.length; i++) { if (list.options[i].selected) { textBox.value = list.options[i].value; break; } }

promptButtonFinish(); } </script>

6 Debugging JavaScript
6.1 Detecting JavaScript errors in Internet Explorer (IE)
In the bottom left corner of the IE window, usually there is the IE blue icon and the text Done. Sometimes the icon is the yellow alert sign and the text says Error on page. That means an error has been detected in JavaScript. By double clicking the icon, an error dialog appears, with the line and text of the error.

6.2 Using Firebug debugger in Firefox

Firefox has a very good HTML/JavaScript debugger, called Firebug. It can be downloaded as a Firefox add-on. Once installed, it will appear like a small bug icon in the bottom toolbar. Clicking this icon will open/close a bottom section of the window, where the Firebug data resides. In this Firebug window some useful operations are: On the Script tab, the script from the current page is displayed. Most of the script is created Cognos. The user created script can be found close to the end of the script tab. For debugging, a breakpoint can be added by clicking at the left of a line in the script. A red circle appears as a bookmark. When the script is stopped at a bookmark, usual debugging is available as inspecting variables or step over/into the code. On the HTML tab, the content of the HTML document is presented as a tree. The user can expand the tree and hover the mouse over HTML tags; the corresponding part in the web page above will appear in light blue. If the user presses the Inspect button, then hover over the web page, the corresponding area in the HTML document is highlighted in light blue. This is very useful when the user wants to find the HTML for a web area.

7 References
7.1 Upgrading JavaScript Applications to IBM Cognos 8.3/8.4
http://www-01.ibm.com/support/docview.wss?rs=0&uid=swg24021973