Bird's Eye View: A Guide

Abstract
This document is provided as a guide to help understand how to use the bird's eye view
functionality provided in Rave through the example of the Bird's Eye View Demo page.

Confidential IBM Corporation

Revision History
Date
mm/dd/yy
11/28/13
12/02/13

Modified by
Ken Smith
Ken Smith

Additions/Changes
Initial version.
Minor revision.

Confidential IBM Corporation

Table of Contents
Bird's Eye View: A Guide................................................................................................1
Abstract.............................................................................................................................2
Revision History...............................................................................................................3
Table of Contents.............................................................................................................4
Demo: How it works.........................................................................................................5
Functionality.................................................................................................................5
Directory Structure........................................................................................................6
Integrator VisControls...................................................................................................6
Creating a VisPanZoomController..........................................................................7
VisPanZoomController options...............................................................................8
Styling the marquee................................................................................................8
Uninstalling a VisPanZoomController.....................................................................8
VisPanZoomController APIs...................................................................................9

Confidential IBM Corporation

Demo: How it works

The "Bird's Eye View" example demonstrates what can be done using Rave and its
"Bird's Eye View" functionality.

Figure 1 Bird's Eye View Demo Page

Functionality
When the "Show Bird's Eye View" option is checked, a smaller window is created and
placed in the bottom right corner. The smaller window will re-size the visualization so it
is completely visible, then overlay a marquee to display the section of the zoomed-in
visualization that is currently displayed in the bigger window.
The marquee can be moved around to change the viewable portion of the visualization
in the bigger window, by using the mouse or the keyboard.

Confidential IBM Corporation

There are also options to change the graphical zoom level: "Zoom In" (zooms in on the
viewable portion of the visualization), "Zoom Out" (zooms out on the viewable portion)
and "Reset" (resets the zoom so the complete visualization is viewable). As well, a
"Specs" option displays a dialog to allow a new specification to be provided for the
visualization.

Directory Structure
The example is available to download and use as a starting point for integrators who
want to use the bird's eye view functionality. All the JavaScript code that creates the
VisControls, handles the interactivity and installs the bird's eye view
(VisPanZoomController) is located in the base HTML file, BirdsEyeDemo.html, at the
root of the download. The styles and fonts are located under the 'style' folder,
documentation is located under the 'docs' folder and the Rave and Dojo JavaScript
libraries are located under the 'js' folder.

Figure 2 Demo directory structure

Integrator VisControls
The Bird's Eye View, created using the VisPanZoomController, requires two
VisControls; one for the overview, one for showing what's highlighted in the overview.
It is up to the integrator to create, place and size these two VisControls. In the example
page, one small VisControl was created as the overview and placed in the bottom right
corner of the bigger VisControl. An icon was also placed over the overview window to
allow a user to minimize (and then restore) the overview window.

Confidential IBM Corporation

Figure 3 Minimize the overview window

Zooming controls were also made available to the user when the bird's eye view was
created (Zoom In, Zoom Out, Reset). These were created for demonstration purposes;
the integrator is responsible for providing any interaction for their user.

Creating a VisPanZoomController
The bird's eye view can be created by installing a VisPanZoomController. The module
must first be required:
require([
other/modules/here,
"com/ibm/vis/widget/VisPanZoomController"
], function(others, VisPanZoomController) {
The controller is then installed by feeding it two VisControls that were already created:
var panZoomController = new VisPanZoomController();
panZoomController.install(masterControl, targetControl);
In the demo example, the masterControl is the VisControl in the overview window and
the targetControl is the VisControl in the bigger window.
The installation of the VisPanZoomController will cause the VisControl in the overview
window to be scaled to fit in the window, so the full visualization is available to be
navigated. A blue transparent marquee will then be overlay on that VisControl to show
where the zooming is occurring on the targetControl, which will be scaled and panned to
reflect the context of the overview window.
The marquee can be moved using the mouse or by using the keyboard's UP, DOWN,
LEFT or RIGHT arrow keys.

Confidential IBM Corporation

VisPanZoomController options
As the marquee is moved around the overview visualization, the target visualization
gets updated as the move happens. This is the default behavior. For some
visualizations, this may not be desirable. To turn this behavior off and only update the
target visualization after the marquee has finished moving, call
setUpdateOnMove(false) before installing the VisPanZoomController.
var panZoomController = new VisPanZoomController();
panZoomController.setUpdateOnMove(false);
panZoomController.install(masterControl, targetControl);
If, as in the example, some interactivity is added to the target VisControl, allowing the
user to zoom and pan the target visualization, the overview window can be kept in sync
by calling update() on the VisPanZoomController.
panZoomController.update();
To reset the navigation and view the whole visualization, a reset() method is provided.
panZoomController.reset();

Styling the marquee

The marquee has a default style than can be changed by the integrator. The CSS
properties of the marquee DIV, referenced by the ravePanZoomMarquee ID, can be
modified after the VisPanZoomController has been installed.
This example uses Dojo to change the background color to red.
domStyle.set(
dom.byId("ravePanZoomMarquee"),
"backgroundColor", "red"
);

Uninstalling a VisPanZoomController
The controller can also be uninstalled. This will remove the marquee and reset the
VisControl scaling and panning.
panZoomController.uninstall();

Confidential IBM Corporation

VisPanZoomController APIs
These are the methods available on the VisPanZoomController and their descriptions.

Method
install(base, target)

uninstall()
reset()
update()
setUpdateOnMove(true |
false)

Description
Creates the VisPanZoomController.
base is a VisControl that will be used as the
overview
target is a VisControl that will display what
the marquee highlights in the overview
Removes the VisPanZoomController.
Resets navigation and view.
Updates the base VisControl to reflect the view of the
target VisControl.
When true, updates the target visualization only after
the marquee has finished moving. When false.
updates the target visualization as the marquee
moves. This is the default.

Confidential IBM Corporation