Some basic techniques for JavaScript

Programming of Cognos Prompts

1
2
3
4
5

6
7

Disclaimer....................................................................................................................2
Introduction..................................................................................................................3
JavaScript Usage for Cognos Prompts........................................................................3
Retrieving prompts......................................................................................................4
4.1
Standard prompts.....................................................................................4
4.2
Other prompts..........................................................................................4
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
Debugging JavaScript..................................................................................................8
6.1
Detecting JavaScript errors in Internet Explorer (IE)..............................8
6.2
Using Firebug debugger in Firefox..........................................................8
References....................................................................................................................8
7.1
Upgrading JavaScript Applications to IBM Cognos 8.3/8.4...................8

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.1.
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.1.

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

Set a value for a

Create a Text Box Prompt and a HTML item containing:

var form = getFormWarpRequest();
var textB = form._textEditBoxXYZ;
textB.value="First value";
canSubmitPrompt();

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

Otherwise the following error message is displayed:

canSubmitPrompt().

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