VISA Network Editor - Technical Documentation

This document describes the use, customization and deployment of the JavaScript client and PHP server.

Directories

The distribution contains two directories: mxgraph contains the mxGraph distribution, and visa contains the VISA specific customizations, examples and documentation for the VISA Network Editor.

The visa directory contains the docs directory for the documentation, and the javascript and php directories for the client and server, respectively.

Requirements

The client requires Firefox 1.5 and later, Microsoft Internet Explorer 5.5 and later, Camino 1.0.2 and later, Opera 9.0 and later, Iceape 1.0 and later, Epiphany 2.0 and later or Galeon 2.0 and later.

The server requires PHP 5.0 or later with libxml (for creating the user object in the graph model and the XML representation) and GD support (for creating the bitmap images of the diagrams on the server-side). Support for TrueType fonts is also recommended for rendering the text in the server-side bitmaps.

TrueType Fonts

The default font for TrueType output ships with the PHP demo and is set in demo.php by overriding the value of mxConstants.DEFAULT_FONTFAMILY. The default value is Vera. Bold fontnames are obtained by appending a Bd-postfix to the fontname in vsGdCanvas.getBoldFont. The resulting default fontname for bold fonts is VeraBd. This can be changed for other environments.

Deployment

To deploy the demos, the complete distribution must be copied to the webroot of a webserver that supports PHP. Then point your browser to the readme in the visa directory at mgraph-visa/visa/readme.html.

For production deployment, only mxgraph/javascript/src and mxgraph/php/src are required. From the visa directory, the javascript/src, php/src and xml/src directories are required.

The directory structure affects the HTML template that is used to render the client (demo.tpl), the PHP file that is used to create the response (demo.php) and the static HTML demo (demo.html).

Server

The server provides an API in the form of vsGraphModel for creating graph models and turning them into an XML file that is understood by the client, that is, the network is mapped to a graph model by use of the vsGraphModel class. A network entity is represented by a cell hierarchy that defines the main label, as well as the title and details of a vertex. A link is represented by a hierarchy that defines the edge-, source- and target labels.

Styles

The graphical representation is defined by one of the following styles. For the title, details, edge labels and demarcation line the title, details, label, sourceLabel, targetLabel and demarcation styles are used internally.

Node Names

The node names are defined by the type argument of the createEntity function. The node name for links created with the createLink function is hardcoded to LINK. The node names can be freely chosen, they do not have any special meaning on the client-side.

Typical node names (entity types) are ROUTER, NETWORK, SWITCH, ASE, ISR, IMA, LAN, SERVER and HOST. The style is normally a lowercase version of the nodename, but the two can vary independently. For switches and any other devices, the default style should be used. This means, the style parameter for the insert function can be omitted.

Attribute Names

The label, title, details, sourceLabel and targetLabel attributes are added to the user object in the createEntity and/or createLink functions. The child cells that represent the additional labels in the graph are using these names for retrieving their labels from the respective parent user object attribute.

The special row attribute is used by the layout algorithm to determine the row in which a vertex should appear. Possible values are 1 (default) and 2. For elements that are located between row 1 and row 2 this attribute can be omitted.

The special endpoint attribute is used by the layout algorithm to determine the devices which are in the endpoint network. Possible values for this optional attribute are 0 and 1.

Any other attributes may be added to the return values of the createEntity and createLink functions using setAttribute. Such attributes may be used for example to specify or customize the entries in the popup menu or define the URL or contents for handling double clicks. The attributes of the user object may be retrieved using getAttribute on the cell argument in the respective hooks on the client-side.

MPLS diagram format

The MPLS diagram format is automatically detected based on the structure of the diagram. The router2 and isr2 shapes do not have respective styles defined, the styles to be used are defaultVertex and isr, respectively as demonstrated in examples 13 and 14. The new shapes use special HTML markup which is parsed in the vsGdCanvas to match the HTML output in the client.

VSAT diagram format

The VSAT diagram format is automatically detected based on the existence of cells with the vsat style. The optional remote location rectangle is created based on the number of devices between the entry point of the endpoint location and the vsat node.

The ISR shapes with 3 columns and separate colors per column use special HTML markup which is parsed in the vsGdCanvas to match the HTML output in the client. The examples 21 and 22 demonstrate the use of the VSAT diagram format and the special markup required for 3 columns. The vertical alignment and label for the endpoint and remote location are also demonstrated in these examples.

Demo

The demo.php file demonstrates the use of the API and a way of deploying the client and diagram in a single response. This is done by replacing the {$xml} placeholder in the demo.tpl template with the XML data that represents the diagram. The placeholder is used as an argument to the main function in the template, which in turn parses the XML and loads it into the graph.

Client

The client provides the vsEditor.doubleClick and vsEditor.popupMenu hooks for handling double clicks and creating a popup menus for right or shift clicks, respectively.

Double Clicks

The doubleClick function is invoked when a cell is double clicked. The graph that contains the cell and the mouse event that represents the double click are passed to the function as arguments. The Demo.doubleClick function demonstrates how to show an URL in a new window when a cell is double clicked.

Popup Menus

The popupMenu function is invoked to create the items of the popup menu. For creating items and submenus, the addItem function is used on the menu object. The Demo.popupMenu function demonstrates how to add submenus and items to execute various functions. (The cell parameter may be null if the background was clicked.)

In both hooks, for accessing the ID of an entity, cell.getId is used. The user object (XML node) is accessed using cell.getValue, and cell.getAttribute is used to retrieve attributes from the user object.

Demo

The demo.html file demonstrates the implementation of these hooks in a static HTML file. The HTML file may be loaded directly into the browser and provides an example double click action and popup menu. The hooks are implemented in Demo.js, which is loaded in the document head after loading the mxClient.

Demo.js defines a subclass of vsEditor that implements the hooks for showing the popup menu and handling double clicks. The container parameter that is passed to the constructor points to the DOM node that is going to contain the HTML markup that represents the graph display. The path argument is used as the base URL for the example diagrams, stylesheets and images that are used in the demo.



© 2009-2011 by JGraph Ltd.