# GraphMLViewer 1.6.1 Documentation

## Usage and Configuration

The following example shows how to embed the GraphMLViewer into a HTLM web page. Note that the file GraphMLViewer.js has to be referenced. This Javascript file defines the necessary functions to start the viewer and to update the Flash Player.

    <html>
    <body>
    <!-- Reference to the Javascript file GraphMLViewer.js -->
    <script type="text/javascript" language="javascript" src="GraphMLViewer.js"></script>

    <script language="javascript" type="text/javascript">
    <!--

    // start the Viewer
    if (!RunPlayer(
        "width", "100%",
        "height", "100%",
        "graphUrl", "example.graphml",
        "overview", "true",
        "toolbar", "true",
        "tooltips", "true",
        "movable", "true",
        "links", "true",
        "linksInNewWindow", "true",
        "viewport", "full"
        )) {
      // if RunPlayer() returns false: Flash Player is either too old or not installed
      // in this case: try to install a current flash player
      if (!InstallFlashUpdate("width", "100%", "height", "100%")) {
        // Flash Player is too old for the auto-update or not installed at all
        // Place alternative content here
        document.write('This content requires the Adobe Flash Player 9.0.38 or higher. '
            + '<a href=http://www.adobe.com/go/getflash/>Get Flash</a>');
      }
    }
    //-->
    </script>
    </body>
    </html>

### Integrate into complex HTML pages

To integrate the viewer into a complex HTML page one can copy the content of the <body> elements (i.e. the `<script>` part) to the appropriate place. Width and height can be configured via the `width` and `height` parameters.

### Configuring the Viewer

The viewer is started using the Javascript method RunPlayer(). This method returns `true` if the viewer could be started successfuly and `false` if not (most likely due to a missing / too old Flash Player). The viewer can be configured via the following parameters. These parameters are passed (as seen in the above example) as key-value-pairs.

Name | Description | Values | Default
--- | --- | --- | ---
Necessary Parameters
graphUrl | The URL of the GraphML file to display | String | -
Optional Parameters
width | The width of the viewer (% or absolute) | size | 100%
height | The height of the viewer (% or absolute) | size | 100%
overview | Whether to show an overview window. "true" enables the overview. | true, false | false
toolbar | Whether to show the tool bar. "true" enables the tool bar, if the view can be moved (movable=true). | true, false | false
movable | Whether the user is allowed to move or zoom the view. "true" enables moving the view. | true, false | false
scrollbars | Whether to show scroll bars if the diagramm is larger than the visible part. "true" enables scroll bars. | true, false | true
tooltips | Whether to show tool tips. "true" enables tool tips. | true, false | false
links | Whether the user is allowed navigate to web links which are attached to graph elements. "true" enables navigation. | true, false | false
linksInNewWindow | Whether to open web links in a new browser window. Web links are opened in a new window if set to "true" | true, false | true
viewport | The section (view) of the diagram which is displayed. Possible parameters are "full", which shows the full diagram, or comma (,) separated coordinates in the order left, top, width, height (e.g. "-100,-100,200,200"). These coordinates define the part of the diagram which is displayed. | "full" or four comma separated numbers | full

### Automatic Flash Player Update

The Javascript file GraphMLViewer.js offers the function `InstallFlashUpdate("width", "100%", "height", "100%")`. This function installs the current Flash Player version. The size of the install window is determined by the "width" and "height" parameter. The function returns `false` if it failed to install the new Flash Player. If you don't want to offer an automatic update omit calling InstallFlashUpdate().

    <html>
    <body>
    <script type="text/javascript" language="javascript" src="GraphMLViewer.js"></script>

    <script language="javascript" type="text/javascript">
    <!--

    if (!RunPlayer(
       ...
        )) {
      document.write('This content requires the Adobe Flash Player 9.0.38 or higher. '
          + '<a href=http://www.adobe.com/go/getflash/>Get Flash</a>');
    }
    //-->
    </script>
    </body>
    </html>

### Customizing GraphMLViewer.js

The file GraphMLViewer.js offers the functions which are necessary to run Flash Player and to load the GraphMLViewer. Usually it is not necessary to customize this file. If you want to customize it, anyway, the following preconditions should be met:

- A Javascript function `GetUrl()` which returns the URL of the current document is needed.
- A Javascript function `LoadGraphML(url)` which loads a GraphML file from the given URL and returns its contents as String is needed.
- Access to these methods has to be granted to the GraphMLViewer by setting `"allowScriptAccess"` to `"always"` in the Flash Player's starting method.

## Provided Files

### Download from www.yworks.com

When you download the GraphMLViewer from yWorks, you will receive a zipped archive which contains besides the documentation the following files:

- example.html: a HTML page which displays a few graphs using the GraphMLViewer.
- examplegraphs/example1.graphml: example diagram in GraphML format.
- examplegraphs/example2.graphml: example diagram in GraphML format.
- GraphMLViewer.js: Javascript file to launch the Flash Player.
- GraphMLViewer.swf: the actual viewer. This file will only run on a local environment.
- crossdomain.xml: a so called crossdomain policy file which allows the viewer to load the graphml file.

### Export from yEd

When exporting a diagram using the Option "HTML Flash Viewer", yEd creates a HTML page which displays the exported diagram using GraphMLViewer. The following files are created:

- [filename].html: the HTML page which calls the viewer.
- [filename].graphml: the exported diagram as GraphML file.
- GraphMLViewer.js: Javascript file to launch the Flash Player.
- GraphMLViewer.swf: the actual viewer. This file will only run on a local environment.
- crossdomain.xml: a so called crossdomain policy file which allows the viewer to load the graphml file.

yEd exports the necessary files in a way that they can be viewed with no further adjustments by opening the HTML file in a browser.

## Preview on a local machine

The following files are necessary to integrate the GraphMLViewer into a HTML page for local preview:

- [myPage].html: your HTML-Seite
- [diagram].graphml: the diagram to display
- GraphMLViewer.js: the Javascript file which launches the viewer.
- GraphMLViewer.swf: the actual viewer (local version)

### Changing the folder structure

If you don't want to place all files in one folder it is possible to customize the folder structure:

- GraphML-files: the `graphUrl` parameter of the `RunPlayer()` function has to be changed to the new URL. The rules for definig URLs in HTML documents apply here, too: If you provide a relative URL (recommended), the URL relates to the HTML file.
- GraphMLViewer.js: change the `src` attribute of the `script` tags, which refers to the file (`<script type="text/javascript" language="javascript" src="GraphMLViewer.js"></script>`) accordingly.
- GraphMLViewer.swf: change the line `var url = "GraphMLViewer.swf";` in the `RunPlayer()` function in GraphMLViewer.js. The rules for definig URLs in HTML documents apply here, too.

## On a Webserver

To publish the created pages on a web server, put the files together as described above. Upload these files to the web server, with the following exceptions:

- The file `GraphMLViewer.swf` is not needed on the web server and thus does not have to be uploaded.
- crossdomain.xml: This file should be placed in the root folder of the web domain (/crossdomain.xml, e.g. if the HTML file's URL is www.foo.com/subfolder/viewer.html, the crossdomain file's URL should be www.foo.com/crossdomain.xml). If such a file already exists add the element `<allow-access-from domain="www.yworks.com"/>` to the list `<cross-domain-policy>`. Please read the following section for more details.

The actual viewer (the Shockwave Flash file, GraphMLViewer.swf), which is loaded in a web environment, will be loaded form the yWorks web site (www.yworks.com).

### Flash Player Security

In a web environment the actual viewer will be loaded from the domain www.yworks.com. Thus, the viewer has to be granted access rights to the GraphML file. Without further configuration swf files which are loaded from domain A (here: www.yworks.com) are not allowed to access data from domain B (e.g. your.domain.com). Domain B can permit this by providing a crossdomain policy file, crossdomain.xml. By default, Flash Player tries to load this file from the root folder of the domain from which the data should be loaded. Example: the HTML page is loaded from http://your.domain.com/en/graphs.html, the graph is loaded from http://your.domain.com/en/graphs/example.graphml. In this case Flash Player attempts to load the file http://your.domain.com/crossdomain.xml.

As web authors do not neccessarily have write access to that folder, GraphMLViewer additionally tries to load the crossdomain policy file from the folder in which the GraphML file is stored. Since Flash Player 10 such an access is only accepted if a so called meta policy grants read access to this folder.

Further information about this topic can be found here:

- Special considerations for users of hosted services
- Understanding the security changes in Flash Player 10

If loading both crossdomain policy files fails, GraphMLViewer loads the GraphML file through the external Javascript (GraphMLViewer.js). For this reason, it is not mandatory to provide a crossdomain policy file. However, loading via Javascript can be considerably slower than loading it directly.

## Using GraphMLViewer without Javascript

It is possible to use the GraphMLViewer without Javascript. In this case it is mandatory to place the file `crossdomain.xml` in the root folder of the domain. The URL from which the SWF-file is loaded has to be set manually. Note that zooming per mouse wheel doesn't work without Javascript on Macintosh systems.

    <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
      id="GraphMLViewer" width="@WIDTH@" height="@HEIGHT@"
      codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
      <param name="movie" value="@VIEWERURL@" />
      <param name="quality" value="high" />
      <param name="bgcolor" value="#ffffff" />
      <param name="allowScriptAccess" value="always" />
      <param name="FlashVars" value="graphUrl=@GRAPHURL@&overview=@OVERVIEW@&toolbar=@TOOLBAR@&tooltips=@TOOLTIPS@&
                                        &movable=@MOVABLE@&scrollbars=@SCROLLBARS@&links=@LINKS@&linksInNewWindow=@WINDOW@&
                                        &viewport=@VIEWPORT@"/>
      <embed src="@VIEWERURL@" quality="high" bgcolor="#ffffff"' +
                width="@WIDTH@" height="@HEIGHT@" name="GraphMLViewer" align="middle"' +
                play="true"
                loop="false"
                allowScriptAccess="always"
                type="application/x-shockwave-flash"
                pluginspage="http://www.adobe.com/go/getflashplayer"
                FlashVars="graphUrl=@GRAPHURL@&overview=@OVERVIEW@&toolbar=@TOOLBAR@&tooltips=@TOOLTIPS@&
                          &movable=@MOVABLE@&scrollbars=@SCROLLBARS@&links=@LINKS@&linksInNewWindow=@WINDOW@&
                          &viewport=@VIEWPORT@">
       </embed>
    </object>

In the above listing, wildcards have been inserted for parameters which have to be customized. Appropriate values for these wildcards are described below. As most of these parameters have to be replaced twice (Internet Explorer and Mozilla / Firefox use different syntaxes), it is best to use your editor's search-and-replace function.

- @VIEWERURL@: The URL of the SWF file. This parameter has to be set differently, according to whether the page is viewed on a local machine or in a web environment. For the local file system it has to be set to the distributed SWF file (`GraphMLViewer.swf` if the viewer is placed in the same folder as the HTML page).
  Before publishing the page on a web server, this URL has to be changed into
  `http://www.yworks.com/products/graphmlviewer/1.0.1/GraphMLViewer.swf`.
- @WIDTH@, @HEIGHT@: Width and height of the viewer in % or absolute pixels.
- @GRAPHURL@: corresponds to the parameter `graphUrl` (see above)
- @OVERVIEW@: corresponds to the parameter `overview` (see above)
- @TOOLBAR@: corresponds to the parameter `toolbar` (see above)
- @MOVABLE@: corresponds to the parameter `movable` (see above)
- @SCROLLBARS@: corresponds to the parameter `scrollbars` (see above)
- @TOOLTIPS@: corresponds to the parameter `tooltips` (see above)
- @LINKS@: corresponds to the parameter `links` (see above)
- @WINDOW@: corresponds to the parameter `linksInNewWindow` (see above)
- @VIEWPORT@: corresponds to the parameter `viewport` (see above)