Creating New Tools

The GAIA viewer offers a toolbox where more advanced tools are located. This page explains how developers can create new tools which correctly interact with the GAIA viewer and other tools.

The GAIA toolbox uses a modular approach so some care is required to allow seamless interaction. The following requirements must be met:

• Tools should be able to operate independently of each other, they should not need knowledge of each other to work correctly.
• Whenever a change is made to the viewer state the tools must notify the main viewer and all other tools of the change.
• Tools must update their own state to follow the viewer and other tools.
• Tools are not permitted to alter the viewer state in response to changes made by other tools; they can only update their own state.

Importing Viewer Functions

Each JavaScript file should insert its functions and variables into a single object which functions as a namespace. (See gaia_data.js for an example of how this is done.) The namespace approach means that JavaScript functions or variable names cannot clash with functions or variables in from other JavaScript files. It also provides are very convenient way of importing variables and functions from one window into another window. When a JavaScript object is copied only a reference to that object is copied. Therefore if a tool window imports data from the main toolbox window both sets of references point to the same data; the data remains consistent. Importing "namespace" objects also imports the functions from that namespace so a tool's HTML page must not link to JavaScript files included by the toolbox or main viewer windows.

Consider the show_status tool. The file starts

if (window.opener) {
  gaiaToolbox = opener.gaiaToolbox;
  gaiaWS = opener.gaiaWS;
  gaiaViewer = opener.gaiaViewer;
  gaiaDate = opener.gaiaDate;
  gaiaDate.installDateMemberFunctions();
  gaiaSprintf = opener.gaiaSprintf;
 }

When window.opener is set the "Show status" tool has been opened by the toolbox window, and a reference to the toolbox window is stored in window.opener. Variables and functions from the gaiaToolbox, gaiaWS etc namespaces is copied into the newly opened "Show status" window. After copying the references (a fast operation) the "Show status" window will be able to call functions from all of the those namespaces. Costly initialisation, such as fetching, parsing and processing the web service data that gaia_ws provides, has been completely avoided.

Creating a new namespace

Continuing the examination of show_status.js reveals

if (!window.gaiaToolboxShowStatus) {
  gaiaToolboxShowStatus = { };

   gaiaToolboxShowStatus.onLoad = function () {
      ...
   };

   ...
}

This code inserts functions and variables into the gaiaToolboxShowStatus object (namepsace), but only if the object does not already exist.

Tracking and altering the main viewer state

The GAIA viewer is event-driven; various components listen for state changes and alter their displayed state in response to those changes. GUI elements can cause state changes in response to user input. An essential property of the GAIA tools is that they interact with the main viewer window. To do this they must follow the displayed state, and optionally provide means to alter the contents of the main viewer window and other tools.

Reading the current and previous state

The current state can be read from the object gaiaViewer.state. The object contains a number of properties which are described in more detail below:

channelOrder

an object of the class gaiaWS.ChannelOrder, indicating how the selected channels are ordered.

channels

an array of objects of the class gaiaWS.Channel. The array is ordered according to channelOrder. Used in situations where multiple channels are displayed (e.g., when the main viewer window is in overview mode).

mode

A string indicating the display mode of the main viewer window. Valid modes are: overview and detailedView.

orientation

an object of the class gaiaWS.Orientation, indicating how images and keograms are to be displayed.

palette

an object of the class gaiaWS.Palette, indicating the colour palette used for greyscale images. See also SummaryPlotRequirements#Colour_palettes

selectedChannel

an object of the class gaiaWS.Channel. Used in situations where only one channel is displayed (e.g., when the main viewer window is in detailed view mode). selectedChannel must be in the channels array.

time

the time for which images are displayed. In overview mode keograms are displayed from the entire day, in detailed view mode thumbnail images are displayed for the selected time.

The previous state can be read from gaiaViewer.previousState which follows the layout described above.

Listening for state changes

Scripts can request to be notified of state changes with the gaiaViewer.registerCallback() function which takes a callback function and an array of state changes for which the callback function should be called. In this way scripts do not have to respond to all state changes, only the relevant ones. When the scripts is notified of a state change the callback function is called with a single parameter, an object whose property names are the state properties which changed, and the property values are the new values for those properties.

There is no method to unregister a callback but this is not necessary. The window for which the callback applies is also passed to gaiaViewer.registerCallback(); if the window is closed the callback function is automatically removed.

Updating the current state

Scripts must not alter the state variables directly but instead call gaiaViewer.updateState(), which takes a single parameter, an object whose property names are the states which should be altered and the property values are the new values for those states. When calling updateState() do not include unchanged state properties.