Linking Google gadgets
Google gadgets display on the dashboard using import gadgets. Google gadgets link to other gadgets to share values in the following ways:
*Link to a data selection gadget by choosing Link from the import gadget menu.
*Link to another Google gadget using the Google publish subscribe framework.
Link Google gadgets to data selection gadgets to receive user selections. The value of the user selection is processed using JavaScript and displays in the import gadget using HTML. For example, a list gadget can send a user selection to a Google gadget. After the Google gadget processes the value it displays a JavaScript alert that contains the user selected value.
If you need to process the linked values before the value is passed to the Google gadget, add JavaScript to the link configuration of the import gadget. For more information about scripting, see Displaying a file on a dashboard.
Linking an import gadget
Link an import gadget to a data selection gadget, such as a list, to receive user selection values. You can now use the Google gadget pubsub feature to receive and process the user selection. Use the gadgets.pubsub.subscribe(channelName, callback) method in the Google gadget to receive the linked value and send it to a callback function, as shown in the following code:
gadgets.pubsub.subscribe("ON_SELECTOR_GADGET_CHANGED", callbackFunction);
The callback function in the Google gadget XML file processes the received value. For example, a callback function reads the incoming message and extracts a value, such as a customer’s address. The callback function then sends the address to an external web service such as Google maps. When the web service responds, the gadget updates with the map showing the location of the address.
Listing 35‑2 shows an example Google gadget that displays changes from a linked data selection gadget. After saving the Google gadget code as an XML file and placing it on a web server, load the file into an import gadget. Link the import gadget to a data selection gadget on the dashboard. Each time the linked data selection gadget changes, the selected value displays in the Google gadget.
Listing 35‑2 Example Google gadget with linking enabled
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="linking example" height="500">
<Require feature="pubsub" />
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
function onEventChange(sender, message) {
document.getElementById('changeme').innerHTML=message;
}
gadgets.pubsub.subscribe("ON_SELECTOR_GADGET_CHANGED", onEventChange);
</script>
<div id="changeme">DEFAULT TEXT</div> <br />
<div>The above text changes according to the current
selection of the gadgets it is linked to.</div>
]]>
</Content>
</Module>
Linking multiple Google gadgets
BIRT dashboards support displaying multiple Google gadgets on the same dashboard. When an import gadget links to a data selection gadget, the message sent by the user selection is a global message. This global message is published across the dashboard on the ON_SELECTOR_GADGET_CHANGED channel and all subscribing import gadgets that listen on the ON_SELECTOR_GADGET_CHANGED channel receive the same message. Google gadgets must listen on unique channel names unless you want them to receive the same user selected values.
For example, a dashboard developer adds an import gadget to show a map of customer addresses and another import gadget to show shipping status on orders. When a user selects the order number from a list gadget that links to both import gadgets, then those import gadgets receive the value and process it. The import gadget that shows shipping status can process the value. The import gadget showing a map expects an address and is unable to retrieve a valid map from an order number.
The issue is resolved when both import gadgets listen on different channels for user selections. Once each Google gadget listens for a unique channel event name, messages go to the correct gadget.
To use a unique channel name in a Google gadget, change the channel name when calling the gadgets.pubsub.subscribe( ) method. The following code shows the channel name changed to Unique_channel_name:
gadgets.pubsub.subscribe("Unique_channel_name", onEventChange);
Only data arriving on the unique channel name triggers the onEventChange function of the Google gadget. Once the Google gadget is listening for a unique channel name, the channel name used to send the value must also change to match the unique channel name.
Add a script to the link settings of the import gadget to match the channel name used in the embedded Google gadget. The following code shows an example of JavaScript that changes the channel event name to Unique_channel_name.
data.event = 'Unique_channel_name';
This script overrides the default channel name before the import gadget passes the information to the Google gadget. The unique channel name must match the name that the embedded Google gadget is listening for.
Figure 35‑5 shows JavaScript in a link event for an import gadget.
Figure 35‑5 Changing the channel event name
All import gadgets listening for the new channel name receive messages from the list gadget. In this example the new channel name is Unique_channel_name.
For more information about adding script to a linking gadget, see Scripting linked gadgets.
Linking Google gadgets together
Gadget developers can build Google gadgets that communicate with one to another using Google’s publish subscribe framework API. One gadget can publish a message and another gadget can subscribe to it. For example, one Google gadget can offer choices to users and another Google gadget can process and display the user’s selections.
Google gadgets that communicate with each other on a dashboard must display inside an import gadget and communicate on the same channel name. The dashboard developer does not link the two import gadgets together because the Google gadget contains all the necessary code to publish and to receive the messages.
Listing 35‑3 shows an example Google gadget that publishes the current date to a custom channel when a user selects the HTML button.
Listing 35‑3 Example of a publishing Google gadget
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Sample PubSub Publisher">
<Require feature="pubsub"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
Published date: <div id="output">...</div><br>
<script type="text/javascript">
function myEvent() {
var message=new Date();
gadgets.pubsub.publish("MY_CHANNEL_NAME", message);
document.getElementById('output').innerHTML = message;
}
</script>
<div>
<input type="button" value="Publish date and time" onclick="myEvent()"/>
</div>
]]>
</Content>
</Module>
Create a second import gadget using the code from Listing 35‑2. Change the channel that the new Google gadget subscribes to so that it matches the channel name of the publishing Google gadget. In the previous example, the channel name was MY_CHANNEL_NAME. Change the subscribe method to use this channel name, as shown in the following code:
gadgets.pubsub.subscribe("MY_CHANNEL_NAME", onEventChange);
Use import gadgets to add both Google gadgets to the same dashboard. When the user chooses the HTML button, the subscribing Google gadget receives the published message. Figure 35‑6 shows the two gadgets communicating.
Figure 35‑6 Communicating between Google gadgets
You do not need to link the two import gadgets together because the Google gadget contains all the necessary code to communicate, to publish, and to receive the message.
Linking public Google gadgets
Google gadgets that the dashboard developer does not own and cannot modify, can receive user selections if the gadget uses the pubsub feature. The dashboard developer adds a script to the import gadget that displays the Google gadget. This script changes the link channel name to match the channel name of the Google gadget. For example, you look at the source code of a Google gadget and see the following code:
gadgets.pubsub.subscribe("MY_PERSONAL_GOOGLE_GADGET", onEventChange);
The channel name used by this Google gadget is MY_PERSONAL_GOOGLE_GADGET.
After linking to a data selection gadget, such as a list gadget, add a script to the link configuration of the import gadget to match the channel name required by the public Google gadget. The following code shows an example of this script, changing the name of the event to MY_PERSONAL_GOOGLE_GADGET:
data.event = "MY_PERSONAL_GOOGLE_GADGET";
When the user makes a selection from the list, the import gadget changes the channel name and passes the message to the Google gadget. For more information about adding script to a linked gadget, see Scripting linked gadgets.