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.