# Anleitung für den GraphMLViewer 1.6.1

## Benutzung und Konfiguration

Um den GraphMLViewer optimal nutzen zu können, ist es nötig, die Datei GraphMLViewer.js zu referenzieren. Diese Javascript Datei enthält die notwendigen Funktionen zum Starten des Viewers und zur Versionskontrolle. Eine aufrufende HTML-Seite kann folgendermaßen aussehen:

    <html>
    <body>
    <!-- Einbinden der Javascript-Datei GraphMLViewer.js -->
    <script type="text/javascript" language="javascript" src="GraphMLViewer.js"></script>

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

    // Viewer starten
    if (!RunPlayer(
        "width", "100%",
        "height", "100%",
        "graphUrl", "yEdViewer.graphml",
        "overview", "true",
        "toolbar", "true",
        "tooltips", "true",
        "movable", "true",
        "links", "true",
        "linksInNewWindow", "true",
        "viewport", "full"
        )) {
      // RunPlayer() gibt false zurueck: der Flash Player is entweder zu alt oder nicht installiert:
      // Versuche, einen aktuellen Player zu installieren
      if (!InstallFlashUpdate("width", "100%", "height", "100%")) {
        // Flash Player ist auch dafuer zu alt oder nicht intalliert
        // Hier kann ein alternativer Inhalt platziert werden.
        document.write('Adobe Flash Player Version 9.0.38 oder höher wird benötigt. '
            + '<a href=http://www.adobe.com/go/getflash/>Get Flash</a>');
      }
    }
    //-->
    </script>
    </body>
    </html>

### Einbinden in komplexere HTML Seiten

Um den Viewer in eine komplexere HTML Seite zu integrieren, kann der Inhalt des <body> Elements (also der `<script>` Teil) an die entsprechende Stelle kopiert werden. Breite und Höhe können über die Parameter `width` und `height` angepasst werden.

### Konfigurieren des Viewers

Der Aufruf des Viewers erfolgt mit der Methode RunPlayer(). Die Methode gibt true zurück, wenn der Viewer gestartet wurde, und false, falls das nicht möglich war (Flash Player ist nicht installiert oder zu alt). Der Viewer kann über folgende Parameter konfiguriert werden, welche, wie im Beispiel oben gezeigt, der Funktion RunPlayer() über Komma getrennt als Name-Wert Paare übergeben werden.

Name | Bedeutung | Zulässige Werte | Standard
--- | --- | --- | ---
Notwendige Parameter
width | Die Breite des Viewers (in % oder absolut) | Größenangabe | 100%
height | Die Höhe des Viewers (in % oder absolut) | Größenangabe | 100%
graphUrl | Die URL der darzustellenden GraphML Datei | Zeichenkette | -
Optionale Parameter
overview | Bestimmt, ob ein Übersichtsfenster angezeigt wird. "true" zeigt das Fenster an. | true, false | false
toolbar | Bestimmt, ob eine Werkzeugleiste angezeigt wird. "true" zeigt die Werkzeugleiste an, sofern das Verändern der Ansicht erlaubt ist (movable). | true, false | false
movable | Bestimmt, ob der Betrachter den angezeigten Ausschnitt verändern (verschieben, vergrößern) kann. "true" läßt das Verschieben des Ausschnittes zu. | true, false | false
scrollbars | Bestimmt, ob bei einem beweglichen Diagramm Rollbalken erscheinen, wenn das Diagramm größer als der sichtbare Ausschnitt ist. Mit "true" werden Rollbalken angezeigt. | true, false | true
tooltips | Bestimmt, ob Tooltips angezeigt werden. "true" zeigt Tooltips an. | true, false | false
links | Bestimmt, ob der Betrachter zu Verknüpfungen (Weblinks) navigieren kann. "true" erlaubt die Navigation. | true, false | false
linksInNewWindow | Bestimmt, beim Navigieren zu Verknüpfungen (Weblinks)diese in einem neuen Fenster geöffnet werden. "true" öffnet die Verknüpfungen in einem neuen Fenster. | true, false | true
viewport | Der darzustellende Ausschnitt des Diagramms. Zulässig sind die Werte "full", wobei das gesamte Diagramm angezeigt wird, oder durch Komma (,) getrennte Koordinaten der Reihenfolge links, oben, Breite, Höhe. Die Koordinaten definieren welcher Teil des Diagramms angezeigt wird, z.B. "-100,-100,200,200" | "full" oder vier durch Komma getrennte Zahlen | full

### Automatisches Update des Flash Players

Die Datei GraphMLViewer.js stellt darüber hinaus noch die Funktion InstallFlashUpdate("width", "100%", "height", "100%") bereit. Diese Funktion installiert die aktuelle Version des Flash Players. Die Parameter "width" und "height" geben die Größe des Install-Fensters an. Die Funktion gibt den Wert false zurück, falls eine Installation nicht möglich war (zum automatischen Update wird ein Flash Player der Version 6 oder höher benötigt). Sollten Sie kein automatisches Update wünschen, können Sie einfach auf den Aufruf der Funktion InstallFlashUpdate() verzichten.

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

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

    if (!RunPlayer(
       ...
        )) {
      document.write('Adobe Flash Player Version 9.0.38 oder höher wird benötigt. '
          + '<a href=http://www.adobe.com/go/getflash/>Get Flash</a>');
    }
    //-->
    </script>
    </body>
    </html>

### Anpassen der Datei GraphMLViewer.js

Wie bereits beschrieben stellt die Datei GraphMLViewer.js die notwendigen Funktionen zum Aufruf des Flash Players und zum Laden des GraphMLViewers zur Verfügung. In der Regel ist ein Anpassen dieser Datei nicht notwendig. Sollten Sie dennoch Anpassungen vornehmen, müssen die folgenden Voraussetzungen gewahrt bleiben:

- Eine Javascript-Methode `GetUrl()`, die die URL des aktuellen Dokuments zurückgibt, muss vorhanden sein.
- Eine Javascript-Methode `LoadGraphML(url)`, die eine GraphML-Datei von der angegebenen URL lädt und deren Inhalt als String zurückgibt, muss vorhanden sein.
- Dem Viewer muss der Zugriff auf diese Methoden erlaubt werden, indem beim Aufruf des Flash Players der Parameter `"allowScriptAccess"` auf `"always"` gesetzt wird.

## Benötigte Dateien

### Download des GraphMLViewers von www.yworks.com

Beim Download des GraphMLViewers von der yWorks Webseite erhält man ein zip-Archiv, welches neben der Dokumentation die folgenden Dateien enthält:

- example.html: eine HTML Seite, die den Viewer aufruft.
- examplegraphs/example1.graphml:Beispieldiagramm im GraphML-Format.
- examplegraphs/example2.graphml:Beispieldiagramm im GraphML-Format.
- GraphMLViewer.js: Javascript-Datei, die den Flash Player startet.
- GraphMLViewer.swf: Der eigentliche Viewer. Diese Datei ist nur auf dem lokalen Rechner lauffähig.
- crossdomain.xml: Eine sog. Crossdomain-Policy-Datei, die dem Viewer den Zugriff auf die GraphML-Datei erlaubt.

### Export aus yEd

yEd erzeugt beim Exportieren mit der Option "HTML Flash Viewer" eine HTML Seite, in der das exportierte Diagramm mit Hilfe des GraphMLViewer angezeigt wird. Dazu speichert yEd folgende Dateien ab:

- [dateiname].html: eine HTML Seite, die den Viewer aufruft.
- [dateiname].graphml: das exportierte Diagramm im GraphML-Format.
- GraphMLViewer.js: Javascript-Datei, die den Flash Player startet.
- GraphMLViewer.swf: Der eigentliche Viewer. Diese Datei ist nur auf dem lokalen Rechner lauffähig.
- crossdomain.xml: Eine sog. Crossdomain-Policy-Datei, die dem Viewer den Zugriff auf die GraphML-Datei erlaubt.

yEd exportiert die notwendigen Dateien so, dass sie ohne weitere Anpassungen durch öffnen der HTML-Datei betrachtet werden können.

## Voransicht auf dem lokalen Rechner

Um den GraphMLViewer in eine HTML Seite zu integrieren, so dass die Seite lokal auf dem Rechner betrachtet werden kann (Voransicht), werden die folgenden Dateien benötigt:

- [myPage].html: Ihre HTML-Seite
- [diagram].graphml: Das darzustellende Diagramm
- GraphMLViewer.js: Javascript-Datei zum Aufruf des Viewers
- GraphMLViewer.swf: Flash-Datei des Viewers

### Anpassen der Verzeichnisse

Wenn Sie nicht alle Dateien in einem Verzeichnis haben wollen, können Sie selbstverständlich die Verzeichnisstruktur anpassen:

- GraphML-Dateien: der graphUrl-Parameter der RunPlayer-Funktion ist entsprechend anzupassen. Dabei gelten die normalen Regeln zum Referenzieren in HTML: Wenn sie eine relative URL angeben (empfohlen), ist diese relativ zur HTML-Datei
- GraphMLViewer.js: passen Sie das `src` Attribut des `script` Tags, mit dem Sie die Datei einbinden (`<script type="text/javascript" language="javascript" src="GraphMLViewer.js"></script>`) entsprechend an. Diese Datei benötigen Sie übrigens nur einmal.
- GraphMLViewer.swf: Die Zeile `var url = "GraphMLViewer.swf";` in der Funktion `RunPlayer()` in der Datei muss entsprechend geändert werden. Eine relative URL ist auch hier wieder relativ zur aufrufenden HTML-Datei.

## Benutzung auf einem Webserver

Um die erstellten Webseiten auf einen Webserver hochzuladen, stellen Sie die notwendigen Dateien wie oben beschrieben zusammen. Laden Sie diese Dateien auf Ihren Webserver hoch, mit folgenden Ausnahmen:

- Die Datei GraphMLViewer.swf wird auf einem Webserver nicht benötigt und muß deswegen nicht mit hochgeladen werden.
- crossdomain.xml: Wenn es Ihre Zugriffsrechte erlauben, sollte diese Datei in das Basisverzeichnis der Web-Domäne geladen werden (/crossdomain.xml, z.B. wenn die HTML-Datei auf www.foo.com/subfolder/viewer.html liegt, sollte crossdomain.xml unter www.foo.com/crossdomain.xml liegen). Existiert bereits eine solche Datei, dann fügen Sie das Element `<allow-access-from domain="www.yworks.com"/>` der Liste `<cross-domain-policy>` hinzu. Der Zweck dieser Datei ist im nächsten Abschnitt ausführlich beschrieben.

Der eigentliche Viewer (die Shockwave Flash Datei, GraphMLViewer.swf), der in der Web-Umgebung geladen wird, wird auf der yWorks Website (www.yworks.com) bereitgehalten.

### Flash Player Sicherheit

Da der eigentliche Viewer auf der yWorks Website bereitgehalten wird, muss dem Viewer explizit der Zugriff auf die GraphML-Datei gestattet werden. Ohne weitere Konfiguration erlaubt der Flash Player SWF-Dateien von Domäne A (hier: www.yworks.com) nicht, auf Daten aus der Domäne B (z.B. your.domain.com) zuzugreifen. Domäne B kann dies aber gestatten, indem sie eine bestimmte Datei bereithält, die Crossdomain-Policy-Datei, crossdomain.xml. Standardmäßig versucht der Flash Player diese aus dem Basis-Verzeichnis der Domäne zu laden, die den Zugriff gestatten soll. Zum Beispiel: die HTML-Seite liegt auf http://your.domain.com/de/graphen.html, der Graph liegt auf http://your.domain.com/de/graphs/example.graphml. Dann versucht der Flash Player die Datei http://your.domain.com/crossdomain.xml zu laden.

Um dem auf der yWorks-Webseite bereitgehaltenen Viewer Zugriff auf die GraphML-Datei zu gestatten, ist es also notwendig, die beigelegte Datei crossdomain.xml in das Basis-Verzeichnis der Domäne zu legen.

Da Autoren von Webseiten nicht unbedingt Zugriff auf dieses Verzeichnis haben, versucht der GraphMLViewer zusätzlich die crossdomain-Datei aus dem Verzeichnis, in dem auch das GraphML liegt, zu laden. Ab Flash Player 10 ist dies nur noch zulässig, wenn eine sog. Meta-Policy existiert, die das Anlegen solcher Dateien erlaubt.

Weitere Informationen über dieses Thema finden Sie auf diesen Seiten:

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

Um diese Probleme zu umgehen, lädt der GraphMLViewer die GraphML-Datei über das externe Javascript, falls das direkte Laden aus den obengenannten Gründen fehlschlägt. Es ist also nicht zwingend notwendig, eine crossdomain-Datei anzulegen. Allerdings ist das Laden über Javascript etwas langsamer als das direkte Laden.

## GraphMLViewer ohne Javascript benutzen

GraphMLViewer kann auch ganz ohne Javascript verwendet werden. In diesem Fall ist es allerdings zwingend erforderlich, die Datei `crossdomain.xml` in das Basisverzeichnis der Domäne zu legen, da sowohl das Nachladen aus dem Verzeichnis, in dem das Diagramm liegt, als auch das Laden des Diagramms über Javascript von Javascript abhängig sind. Außerdem muss die URL, von der die SWF-Datei geladen wird, von Hand angepasst werden. Beachten Sie darüber hinaus, dass Zoomen per Mausrad auf Macintosh Rechnern ohne Javascript nicht funktioniert.

    <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>

Im obigen Listing sind für die anzupassenden Parameter Platzhalter eingefügt, die wie nachfolgend beschrieben zu ersetzen sind. Da die meisten Parameter doppelt anzugeben sind (Internet Explorer und Mozilla / Firefox benutzen eine unterschiedliche Syntax), bietet sich die Suchen und Ersetzen-Funktion Ihres Editors hierfür an.

- @VIEWERURL@: Die URL, unter der die SWF-Datei geladen wird. Dieser Parameter unterscheidet sich, je nachdem, ob die Datei auf dem lokalen Dateisystem betrachtet wird, oder auf einem Webserver liegt. Für das lokale Dateisystem ist der Ort, an dem die mitgelieferte SWF-Datei liegt anzugeben (`GraphMLViewer.swf`, wenn der Viewer im gleichen Verzeichnis wie die HTML-Datei liegt).
  Vor dem Veröffentlichen auf einem Webserver ist diese URL zu ändern in
  `http://www.yworks.com/products/graphmlviewer/1.0.1/GraphMLViewer.swf`.
- @WIDTH@, @HEIGHT@: Breite und Höhe des Diagramms in % oder absolut.
- @GRAPHURL@: entspricht dem Parameter `graphUrl` (siehe oben)
- @OVERVIEW@: entspricht dem Parameter `overview` (siehe oben)
- @TOOLBAR@: entspricht dem Parameter `toolbar` (siehe oben)
- @MOVABLE@: entspricht dem Parameter `movable` (siehe oben)
- @SCROLLBARS@: entspricht dem Parameter `scrollbars` (siehe oben)
- @TOOLTIPS@: entspricht dem Parameter `tooltips` (siehe oben)
- @LINKS@: entspricht dem Parameter `links` (siehe oben)
- @WINDOW@: entspricht dem Parameter `linksInNewWindow` (siehe oben)
- @VIEWPORT@: entspricht dem Parameter `viewport` (siehe oben)