Integrate Your App with Constellation Roamer

Constellation has four basic components:

the Constellation SWF, a Flash movie that displays the visualization,
the XML configuration file which usually resides in the same directory as the Constellation SWF,
the webpage which embeds the Constellation SWF, and
the data URL, that is, the URL where the graph data is retrieved—either a REST-like interface or an XML file.

Placing the Visualization in a Webpage

Embedding the Constellation SWF is just like embedding any other Flash movie. You can download sample HTML code by right-clicking the link below and choosing "Save as...".

Sample HTML file for embedding the Constellation SWF

Note that Constellation can receive three parameters as flash_vars.

[selected_node_id]: The ID of the node which should be selected when the visualization loads. It's usually a good idea not to leave this value out, but if you do, the default value is "1".
[instance_id]: The ID of the particular instance of the Constellation interface. This parameter can be passed on to the data URL, allowing different datasets to be displayed for each instance. This also allows developers to expose only the data that a user has permission to see. Optional.
[config_url]: The URL where the XML configuration file can be found. Normally this value can be omitted or left blank and the Constellation SWF will look for the config file in its own directory. Optional.

Configuring the Visualization

The configuration file includes parameters for customizing the appearance and the interface for loading data. It also contains licensing information. You can download a sample configuration file by right-clicking the link below and choosing "Save as...".

Sample XML configuration file

Loading a Node Graph into the Visualization

There are currently two methods for getting your data into the Constellation visualization. The first option is to put all the graph data into an XML file which is loaded when the Visualization starts up. The other option is to use a REST-like interface where data can be loaded as needed.

Loading graph data from an XML file

Using an XML file to store graph data is the simpler of the two methods but is not appropriate for large datasets. If the XML file gets too big, then there will be a noticable delay before the visualization renders.

The format for representing the graph data in XML is a list of nodes and a list of edges. Each node element must have a unique ID and each edge element must have a unique ID. Edge elements are also required to have the attributes "tail_node_id" and "head_node_id" indicating the IDs of the nodes that the edge connects.

You can download a sample XML file by right-clicking the link below and choosing "Save as...".

Sample XML graph data

Once the XML file has been created, it needs to be uploaded to a webserver and the data.url parameter should be set to the URL of the XML file.

Loading graph data from a REST-like interface

Unlike the first method, above, the REST-like interface may receive several requests from a Constellation SWF. As the user navigates the graph, new data is loaded from the server in the form of a tree. The tree is defined by the root node and a depth parameter. For example, if the SWF requests a tree with a depth of one, the script should return just the root node. If the depth parameter is set to two, the script should return the root node, its neighbor nodes, and all edges between those nodes. For a depth of three, the script would return the root node, its neighbors, their neighbors, and all edges connecting those nodes.

To receive the parameters for the root node ID and the tree depth, the strings "[node_id]" and "[depth]" need to be placed somewhere in the value of data.url in the XML configuration file. Here are two examples:

<url>http://example.com/tree.php?
root=[node_id]&depth=[depth]</url>

<url>http://example.com/tree/[node_id]/[depth]</url>

The REST-like interface should return the graph data in the same format as in the XML file method above. You can download a sample XML file by right-clicking the link below and choosing "Save as...".

Sample XML graph data (REST-like interface)

One important difference between the returned XML is that each node element has an attribute, "depth_loaded." This value must indicate the depth of the tree rooted at that node, as contained in the response. For example, if a request was made for the tree rooted at node A with a depth of two, the node element for node A will have a depth_loaded value of two since the response includes that node and its neighbors. The neighbors of node A will also be included in the response and their depth_loaded attribute should have a value of one since not all their neighbours will be included in the response.

The depth_loaded attribute is used by the Constellation SWF to determine whether more information needs to be loaded from the server. When the depth_loaded value of a node is less than the data.min_load_depth value in the configuration file, a new request will be sent to the server.

Interacting with Constellation via Javascript

The embedding webpage can communicate with Constellation Roamer using Javascript. To enable this feature, set integration.use_javascript to 'true' in the XML configuration file.

If you need to keep track of multiple instances, set the integration.include_instance_id parameter to 'true' and all javascript method calls will include the instance ID as the first parameter.

Event Handler Callbacks

When integration.use_javascript is set to 'true' the following methods must be defined in the head of the embedding webpage.

void constellationRoamer_onLoaded(): Called when the Flash movie is first loaded.
void constellationRoamer_onChange(string nodeID): Called when user interaction causes the selected node to change. Not that calling the setSelectedNodeID does not trigger this event handler.
void constellationRoamer_onClick(string nodeID): Called when the user clicks a node. If the user drags the node or holds the mouse down for too long, the click is ignored and this event handler is not triggered.
void constellationRoamer_onDoubleClick(string nodeID): Called when the user double clicks a node. If the user drags the node or holds the mouse down for too long, the click is ignored and this event handler is not triggered.
void constellationRoamer_onEdgeClick(string edgeID): Called when the user clicks an edge.
void constellationRoamer_onEdgeDoubleClick(string edgeID): Called when the user double clicks an edge.

Flash Movie Methods

The following javascript methods can be called on the Flash movie.

string getSelectedNodeID(): Returns the ID of the currently selected node.
void setSelectedNodeID(string nodeID): Selects the node with the given ID. For dynamic data interfaces, a request will be made to the server if the node hasn't been loaded already.
void clearGraphData(): Clears the graph data model.
void reloadGraphData(): Reloads the graph data model. In the static XML interface mode, this reloads the entire graph. For the REST tree interface mode, only the tree rooted at the currently selected node is reloaded.

Find out what you get with your purchase »