Use JavaScript to process or change a user-selected values before it is used with report, Reportlet, and import gadgets. You can also use JavaScript to interact with global variables on the dashboard and change default report parameters. For example, you can validate or change user selections, display custom dialogs, or send values to a JavaScript function.
When a user selects or changes a value in a data selection gadget, such as a list, an onChange event is published to the dashboard. This onChange event triggers gadgets subscribing to this list to update their contents with the new selection.
Use the onChange function to access gadget messages sent by data selection gadgets. This enables you to use JavaScript to access and process user selections. You can also view these values in a JavaScript debug console of your web browser or in JavaScript alerts.
How to add JavaScript to a gadget
1 In a gadget menu choose link. Figure 33‑5 shows the gadget menu of a bar chart.
Figure 33‑5 Opening link options for a chart gadget
2 In Link, choose Edit Script in the same row as the selected data selection gadget. Figure 33‑6 shows two linked gadgets that you can use with JavaScript. Choose Edit Script in the row of the Product Line gadget.
Figure 33‑6 Adding JavaScript to a data selection gadget
3 In Edit Script, select Customize and type the following text as shown in Figure 33‑7:
alert("New Selected Value");
Figure 33‑7 Customizing the onChange event for a data selection gadget
4 Choose OK.
5 Test the new script by making a change in the data selection gadget that uses the link. Figure 33‑8 shows an example of a JavaScript alert that is created each time a use selects a value in a data selection gadget.
Figure 33‑8 Testing the new onChange JavaScript event
Choose OK to close the JavaScript alert.
Using JavaScript objects to retrieve values
JavaScript objects are used by gadgets to send and receive values. You can access these objects to read and edit the values. Scripts interact with the following JavaScript object data:
event
The event name, for example:
"ON_SELECTOR_GADGET_CHANGED"
data
The data object that includes the entire message published by the data selection gadget. The following example of a data object message is sent by a list gadget named PRODUCTLINE with Trains and Ships selected:
This object refers to the report or Reportlet gadget receiving the published message. You can use this data to verify values in parameters and set conditions for updating a linking gadget.
The following example shows the value of thisGadget for a BIRT report design file with a customer name parameter:
You can view a user selection using a web browser’s JavaScript console. The following JavaScript code displays the publisher of a linked gadget event in a JavaScript console that supports the JSON method, such as Internet Explorer:
console.log(JSON.stringify(publisher,"",1));
The following JavaScript code displays the publisher object of a linked gadget event to a JavaScript console that supports the toSource method, such as Firefox:
console.log(publisher.toSource());
In both Internet Explorer, Firefox, and Chrome you can inspect the JavaScript object using the following code:
console.dir(publisher);
This code writes the data exchanged between gadgets to the JavaScript console of the web browser. JavaScript code gives different results depending on the web browser. For example the toSource( ) method works in Firefox but not in the Internet Explorer or Safari web browser. Check your web browser’s documentation for supported JavaScript debug tools.
Displaying values in Internet Explorer
Starting in Internet Explorer 9, the Developer Tools can view JavaScript values in the console pane. For example, the following code in a chart gadget’s link configuration runs when a user changes the list that the chart links to:
console.log(JSON.stringify(event,"",1));
console.log(JSON.stringify(publisher,"",1));
console.dir(data);
console.log(JSON.stringify(thisGadget,"",1));
Figure 33‑9 shows the console result of a user selecting a value in the list gadget. This console is in Developer Tools of Internet Explorer 11.
Figure 33‑9 Viewing the console in Developer Tools
Some JavaScript objects only display the word [object Object]. For example, JSON.stringify( ) works in Internet Explorer but it does not display JavaScript objects in the Developer Tools console.
Use the Internet Explorer watch pane in break mode to either expand these objects or make a list of objects to watch, as shown in Figure 33‑10.
Figure 33‑10 Viewing JavaScript objects in Developer Tools
Displaying selected values
You can extract specific parts of the message, for example:
alert(publisher._gadgetTitle);
This example creates a JavaScript alert displaying the name of the gadget that published the message.
Using linked values
Scripts can process the value received from a linked gadget and execute additional JavaScript code. For example, to display a JavaScript alert containing the values arriving at a gadget, add the following script to the link:
JavaScript can change user selected values, such as changing the selection value of France to FR. This enables you to select parts of a user selection, such as, extracting a tracking number or part of a phone number, and apply additional changes to the selection.
Scripts can read and change selection values before those values are used by report gadgets or import gadgets. Scripts can also write user selection values to a global variable on the dashboard page.
For example, a script on an HTML gadget can write the value of a user selection to a global variable using the following code:
var key = data.value.keys();
var received = data.value.get(key).values[0];
window.tracking = received;
An HTML gadget can retrieve the global variable with the following HTML code:
<scripttype="text/javascript">
var message = parent.tracking;
document.write(message)
</script>
Refresh the HTML gadget to load the global variable. You can refresh a gadget by selecting Refresh from the gadget menu. If you need an event to trigger additional JavaScript code, put the code into a Google gadget and trigger the code with the pubsub feature.
Reading and writing parameter values
You can use scripts to read and write parameter values for report and Reportlet gadgets. The thisGadget object supports a getCurrentReportParameters( ) function to view and change report parameters.
Scripts support the following actions:
Set conditions for using a data selection value.
Change the value of the linked data selection.
Change the parameter value of the report or Reportlet gadget.
For example, a dashboard developer makes a report gadget to display country information in a BIRT design file. The developer expects users to select a country from a linked list gadget. The BIRT design file has parameters for Country, State, and City but the developer only wants to show country information. Listing 33‑1 shows a script to remove current parameter values for State and City.
Listing 33‑1 Example script for reading and writing report parameters
var params = thisGadget.getCurrentReportParameters();
for ( var i = 0; i < params.length; i++ )
{
var param = params[i];
if ((param.getName() == 'State') || (param.getName() == 'City'))
event
