201119Jun

jQuery-Tutorial: SVG-Daten mit jVectorMap darstellen

Kürzlich berichtete ich über das jQuery-Plugin "jVectorMap", mit dem sich SVG-Daten interaktiv im Browser einbetten lassen. Die Daten werden dabei als JavaScript-Objekte eingelesen und können dann im Browser vergrößert, verschoben und mit Informationen versehen werden. Das Plugin eignet sich also nicht nur für Welt- oder Landkarten, sondern für SVG-Material aller Art.
Da die Frage aufkam, wie sich eigene SVG-Karten mit dem Plugin einbinden lassen, habe ich eine kleine Anleitung verfasst, in der ich die benötigten Schritte zeige. Die eigentlichen SVG-Daten können mit Programmen wie Inkscape oder Adobe Illustrator erzeugt werden.

jVectorMap

Auf der Website des jVectorMap-Plugins stehen das eigentliche Skript sowie vorgefertigte Karten zum Download bereit. So gibt es bereits eine komplette Weltkarte und auch eine Karte von Deutschland im benötigten JavaScript-Format. In diesem Tutorial geht es nun darum, eigene SVG-Karten in das erforderliche Format zu bringen und in jVectorMap zu integrieren.

Bevor es an die Erstellung der SVG-Karte geht, will ich kurz die Implementierung von jVectorMap erläutern. Dazu habe ich ein einfaches HTML-Template erstellt, in dem ich die Karte einbinden will. Im Wesentlichen sieht die DOM-Struktur so aus:

  • <html>
  • <head>
  • <title>jVectorMap-Beispiel</title>
  • <link href="jquery.vector-map.css" />
  • <script src="jquery.min.js"></script>
  • <script src="jquery.vector-map.js"></script>
  • <script src="beispiel_karte.js"></script>
  • <script type="text/javascript">
  • $(document).ready(function(){
  • // jQuery-Code
  • });
  • </script>
  • <style type="text/css">
  • #karte {
  • width:800px;
  • height:600px;
  • }
  • </style>
  • </head>
  •  
  • <body>
  • <div id="karte"></div>
  • </body>
  • </html>

Der kompletten Inhalt der Datei findet sich hier. Es wird also ein Container-Element (hier mit der ID "karte") benötigt, in dem die interaktive Karte als SVG-Element erzeugt wird. Der Vorteil von SVG kommt hier bereits zum Tragen, denn die Größe von 800×600 Pixeln ist variabel und so kann hier ein beliebiges Format angegeben werden. Man sollte an dieser Stelle jedoch die Größe der Arbeitsfläche im Kopf behalten, auf der die Vektorflächen angelegt wurden.
Die Daten der Karte befinden sich in der Datei "beispiel_karte.js" als JavaScript-Objekt. Hier werden die eigentlichen Pfade, Farbwerte und andere Optionen von jVectorMap hinterlegt. Ich habe diese Datei so formatiert, dass sie lesbar ist. Ohne Pfad-Informationen sieht eine Kartendatei dann etwa so aus:

  • $.fn.vectorMap("addMap", "beispiel_karte", {
  • "width": 800,
  • "height": 600,
  • "pathes": {
  • "kuerzel1": {
  • "path": "",
  • "name": "Name der Fläche 1"
  • },
  • "kuerzel2": {
  • "path": "",
  • "name": "Name der Fläche 2"
  • }
  • }
  • });

Alternativ gibt es die Datei auch wieder hier als Text-Datei zum Download. Wie man sieht, werden in Zeile 2 und 3 die Maße der Grafik festgelegt. Diese müssen aus der SVG-Grafik entnommen werden, um die korrekten Proportionen und Positionen beizubehalten. Im Objekt "pathes" (ab jVectorMap 1.x "paths") befinden sich schließlich die einzelnen Flächen der Karte. Hier müssen ein Kürzel, die eigentlichen Pfad-Informationen sowie ein Name hinterlegt werden. Die Kürzel dienen zur Identifizierung und können für zusätzliche Effekte verwendet werden. Das Attribut "name" stellt die Information dar, die eingeblendet wird, sobald sich der Mauszeiger über dem entsprechenden Element befindet.
Die wichtigsten Informationen enthält nun das "path"-Attribut. Hier müssen jetzt die Pfade der SVG-Grafik eingefügt werden. Dazu erstelle ich zwei einfache Flächen in Adobe Illustrator.

Adobe Illustrator - Eine Beispielkarte

Wichtig bei der Erstellung ist die Auswahl eines Pfad-Werkzeugs wie dem "Zeichenstift". Objekte wie Rechtecke oder Polygone, die über ein anderes Werkzeug erstellt wurden, müssen über das Menü "Objekt -> Zusammengesetzter Pfad -> Erstellen…" umgewandelt werden. Das Plugin funktioniert also nur, wenn im finalen SVG-Code lediglich "path"-Elemente vorhanden sind. Andere Objekte wie "rect", "shape" oder "polygon" werden nicht verarbeitet (dann muss die Fläche zuerst umgewandelt werden).
Sobald die Karte vollständig erstellt ist, muss sie als SVG-Grafik exportiert werden. In Adobe Illustrator geht dieser Schritt über das Menü "Datei -> Speichern unter…". Im folgenden Dialog muss dann im Feld "Dateityp" die Option "SVG" ausgewählt und anschließend die "Speichern"-Schaltfläche betätigt werden. Anschließend erscheint der "SVG-Optionen"-Dialog, in dem noch eine Einstellung vorgenommen werden kann.

Adobe Illustrator - SVG-Optionen

Im Feld "Dezimalstellen" kann der Wert "2" eingetragen werden. Dann kann der eigentliche SVG-Code über die Schaltfläche "SVG-Code anzeigen…" im Browser angesehen werden. In verkürzter Form dürfte der Code so aussehen:

  • <?xml version="1.0" encoding="utf-8"?>
  • <svg x="0px" y="0px"
  • width="841.89px" height="595.28px" viewBox="0 0 841.89 595.28" enable-background="new 0 0 841.89 595.28" xml:space="preserve">
  • <path fill="#99BC52" d="M340,276l-2,42l-72,30l-99,136l101-273L340,276z"/>
  • <path fill="#99BC52" d="M369,327c0,0,36-82,39-83s80-17,80-17l58-79l128-54l14,9l-82,69l-23,123L429,470L369,327z"/>
  • </svg>

Der komplette Code der Beispiel-Grafik findet sich hier. Für die Verarbeitung in jVectorMap sind jetzt die "path"-Elemente interessant: Hier wird lediglich der Wert des "d"-Attributs benötigt. Ich habe die entsprechenden Stellen in der Code-Ansicht unterstrichen dargestellt. Diese Angaben müssen also kopiert und an den richtigen Stellen in der JavaScript-Datei "beispiel_karte.js" eingefügt werden. Für jede Fläche muss ein separates Objekt mit den Attributen "path" und "name" angelegt werden (in meinem Fall gibt es daher 2 Objekte). Wichtig ist, dass die Pfad-Informationen keinen Zeilenumbruch aufweisen. Bei komplexeren Pfaden ist das der Fall und hierfür sollte ein Tool wie TextFixer.com verwendet werden, um die Zeilenumbrüche zu entfernen. Schließlich sollten auch noch die Attribute "width" und "height" aus Zeile 3 übernommen werden. Diese Werte werden am Anfang der JavaScript-Datei eingefügt. Der finale Code von "beispiel_karte.js" wäre dann:

  • $.fn.vectorMap("addMap", "beispiel_karte", {
  • "width": 842,
  • "height": 595,
  • "pathes": {
  • "kuerzel1": {
  • "path": "M340,276l-2,42l-72,30l-99,136l101-273L340,276z",
  • "name": "Name der Fläche 1"
  • },
  • "kuerzel2": {
  • "path": "M369,327c0,0,36-82,39-83s80-17,80-17l58-79l128-54l14,9l-82,69l-23,123L429,470L369,327z",
  • "name": "Name der Fläche 2"
  • }
  • }
  • });

Die Text-Version gibt es hier. Die Farben der Flächen können dann über die jVectorMap-Konfiguration vorgenommen werden. Um die SVG-Karte nun in einfacher Form zu integrieren, muss im "script"-Bereich des beispielhaften HTML-Templates folgender Code eingefügt werden:

  • $(document).ready(function(){
  • $("#karte").vectorMap({
  • map: "beispiel_karte",
  • });
  • });

Danach sollte die Karte im Browser angezeigt werden. Für die Interaktivität sorgt das Plugin. Ohne besondere Einstellungen werden die Standard-Farben für die Flächen und den Hintergrund verwendet. Das Ganze sollte dann so aussehen:

jVectorMap - Ein Beispiel

Damit wäre die Implementierung von jVectorMap soweit abgeschlossen. Das Plugin bietet noch zusätzliche Features wie Events oder die Verarbeitung von besonderen Daten. Zum Abschluss hier noch eine Konfiguration mit weiteren Einstellungen, die für andere Farben und einen Transparenz-Effekt sorgen:

  • $(document).ready(function(){
  • farben = {};
  • farben["kuerzel2"] = "#98BC53";
  •  
  • $("#karte").vectorMap({
  • map: "beispiel_karte",
  • backgroundColor: "#4E4943",
  • colors: farben,
  • hoverOpacity: 0.7,
  • hoverColor: false
  • });
    });

Hier wird also das Objekt "farben" definiert, in dem die IDs der Flächen im JavaScript-Objekt angesprochen werden können. Dadurch lassen sich die Flächen mit individuellen Farben versehen. Ebenso wurde das Attribut "hoverColor" auf "false" gesetzt, so dass die Einstellung "hoverOpacity" greift und die Flächen entsprechend in ihrer Transparenz reduziert werden, sobald der Mauszeiger darüber bewegt wird.
Insgesamt ist die Integration einer SVG-Karte in jVectorMap einfach: Lediglich die Erstellung des JavaScript-Objekts, welches die Pfad-Informationen enthält, kann etwas mehr Zeit in Anspruch nehmen. Die Arbeit wird jedoch belohnt, da mit dem jQuery-Plugin eine erstklassige Methode zur Verfügung steht, um skalierbare Grafiken auf einer Website unterzubringen.

Das fertige Beispiel kann unter diesem Link angesehen werden.

Das komplette Beispiel-Projekt mit allen benötigten Dateien gibt es auch hier zum Download.

UPDATE
jVectorMap ist inzwischen in der Version 1.x erschienen. Hier hat sich die Objekt-Bezeichnung von "pathes" auf "paths" geändert. Wenn ihr das Beispiel herunterladet und eine aktuelle jVectorMap-Version verwenden wollt, müsst ihr das Objekt umbenennen.