Rauchzeichen vom Widget-Hügel
Ein eigenes Widget für den Web AppBuilder for ArcGIS entwickeln
Anwender können miit dem Web AppBuilder for ArcGIS auch ohne Programmierkenntnisse eine eigene Webanwendung erstellen. Hierzu stellt der AppBuilder eine umfangreiche Bibliothek zur Verfügung, um GIS-Funktionen einzubinden und Layouts für solche Endgeräte zu realisieren. Doch was tun, wenn dies nicht ausreicht? In diesem Fall bietet der WebApp Builder for ArcGIS Entwicklern ein umfangreiches Framework, um eigene Widgets und Themes zu entwickeln. In diesem Blog wollen wir uns die Entwicklung eines eigenen Widgets etwas genauer ansehen.
Struktur einer Web AppBuilder Anwendung
Zum Einstieg betrachten wir die Struktur einer fertigen Web AppBuilder Anwendung. Diese erhalten wir, indem wir eine im Builder konfigurierte App downloaden. Der Export enthält einen Ordner mit verschiedenen Dateien und Unterordnern. Kopiert man diesen auf einen eigenen WebServer, ist die Anwendung dort sofort lauffähig. Da wir die Anwendung aber zunächst noch erweitern wollen, werfen wir einen Blick auf die Struktur dieses Ordners. Die Namen der Unterordner geben Aufschluss über ihre Funktion: Die Unterordner „images“ und „themes“ sind für das Layout der Anwendung verantwortlich. Der Ordner „jimu.js“ enthält den Quellcode mit den Kernfunktionalitäten der Anwendung. In „libs“ sind Third-Party-Libraries enthalten. Diese beiden Ordner sollten möglichst nicht bearbeitet werden.
Die oben erwähnten GIS-Funktionsbausteine findet man im Ordner „widgets“. In der, im Stammverzeichnis befindlichen, Datei „config.json“ ist beschrieben, wie diese in die Anwendung eingebunden werden. Diese beiden Stellen sind somit die interessantesten für den Entwickler.
Abbildung 1: Ordnerinhalte einer exportierten Web-Applikation
Bestandteile eines Widgets
Im Builder werden unter „client\stemapp\widgets\samplewidgets“ einige Templates zum Entwickeln eigener Widgets mitgeliefert. Wir verwenden als Einstiegspunkt das CustomWidgetTemplate, indem wir dieses in den Widget-Ordner unserer Anwendung kopieren, passend benennen und in der Datei „config.json“ zum „widgetPool“ hinzufügen. Betrachten wir die Bestandteile des Templates fällt auf, dass wie auch im Rest der Applikation Seitenaufbau, Layout und Funktionalität getrennt sind. Eine HTML-Datei („Widget.html“) definiert Platzhalter in Form von <div>-Containern, die zwar die Bestandteile der Benutzeroberfläche grob definieren, jedoch üblicherweise keine sichtbaren Inhalte enthalten. Das Aussehen aller UI-Elemente wird über Stylesheets (Unterordner „css“) definiert. Die eigentliche Logik findet sich in den JavaScript-Dateien wieder, wobei der Einstiegspunkt die Datei „Widget.js“ ist.
Die Internationalisierung der Inhalte wird umgesetzt durch das Modul „i18n“ [i] des JavaScript-Frameworks „Dojo“, das der ArcGIS API for JavaScript zugrunde liegt. Die dazugehörigen Tabellen befinden sich im Unterordner „nls“ [ii]. Außerdem lassen sich Konfigurationseinstellungen auf Widget-Ebene in der Datei „config.json“ ablegen. Die Datei „manifest.json“ ist zur Angabe von Metainformationen gedacht, wie dem Namen des Widgets, dem angezeigten Label, einer Versionsnummer oder Angaben zum Autor. Die beiden Dateien sind vor allem wichtig wenn das Widget nicht nur in einer Anwendung integriert werden soll, sondern auch dem Builder zur Wiederverwendung in anderen Apps zur Verfügung gestellt wird.
Abbildung 2: Aufbau eines Widgets
Widget.js – der Lebenszyklus
Ein Widget muss von der Klasse BaseWidget ableiten. Die Grundstruktur dieser Klasse entspricht dem Lebenszyklus eines Widgets: Die Funktion startup() ist dafür gedacht, allerlei Dinge zur „Geburt“ des Widgets zu regeln. So können zum Beispiel GUI-Elemente instanziiert und im HTML-Code platziert werden – noch unsichtbar für den User. Für den weiteren Lebenszyklus des Widgets lassen sich Funktionen definieren, die in bestimmten Situationen ausgeführt werden: onOpen() wird automatisch beim Öffnen des Widgets ausgelöst. Hier können Aktionen abgefahren werden, die direkt im Anschluss an das Öffnen geschehen sollen – beispielsweise Animationen, die der User zu Beginn sehen soll, oder das Starten einer Mediendatei. Weitere Standardsituationen werden durch onMaximize(), onSignIn() oder onClose() abgedeckt. Die Methode destroy() ist für Aufräumarbeiten gedacht. Hier können initialisierte Objekte aus dem Speicher entfernt werden.
Da es sich bei ArcGIS WebApps natürgemäß um geozentrische Anwendungen handelt, ist ein Kartenfenster immer inbegriffen. Für den Widget-Code ist das Kartenobjekt stets per this.map verfügbar. So lassen sich Informationen wie der aktuelle Kartenausschnitt oder die verfügbaren Grafiken auf einem Layer abrufen, das Widget kann auf Aktionen in der Karte reagieren oder die Karte steuern: Die Klasse esri/Map stellt dazu Methoden wie addLayer() oder centerAndZoom() zur Verfügung.
Funktionen und Eventhandler
An dieser Stelle machen wir einen kleinen Exkurs zu JavaScript-Funktionen. Funktionen werden „manuell“ aufgerufen, um beispielsweise eine Berechnung durchzuführen, bevor man mit den Ergebnissen weiterarbeitet. Das Auslagern des Codes aus dem allgemeinen Fluss in eine Funktion oder in eine separate Businessklasse dient der Übersicht, der Wiederverwendbarkeit und dem Einschränken des Gültigkeitsbereichs von Variablen. Tut man das nicht, erhält man den vielzitierten „Spaghetticode“ – ein lineares, nicht wartbares Monster mit wachsender Anzahl an unerwünschten Nebeneffekten, proportional zur Länge des Codes.
Eventhandler sind spezielle Funktionen, die an andere Objekte angeschlossen werden und darauf reagieren. Sie sind besonders praktisch bei asynchronen Vorgängen, und eine moderne JavaScript-Applikation ist voll davon: Jeder Zugriff auf externe Ressourcen, sei es das Laden von referenziertem JavaScript-Code, das Parsen eines RSS-Feeds oder die Ausführung einer Geoprocessing-Funktion, wird üblicherweise asynchron ausgeführt, da die Dauer einer solchen Aktion nicht vorhersehbar ist. Ohne Events bliebe einem nichts anderes übrig als den kompletten Programmfluss auf Eis zu legen und auf die Antwort zu warten. Bei der asynchronen Ausführung läuft die Applikation weiter, die GUI reagiert auf Benutzereingaben und beim Eintreffen der Daten wird ein Event gefeuert. Das kann man sich vorstellen wie ein Rauchzeichen: Unser Indianer hinter dem Hügel ist der angeschlossene Eventhandler: Dieser sieht das gefeuerte Event, und kann z.B. ein GUI-Element mit den übermittelten Daten füllen und es gleichzeitig aktivieren, sodass es von nun an für Benutzerinteraktionen zur Verfügung steht.
Wer jetzt besonders gut aufgepasst hat, hat sicher schon verstanden, dass die im vorigen Kapitel erwähnten Standard-Funktionen nichts anderes sind als EventHandler, die auf Events der WebApp reagieren: Der Indianer hinter dem Widget-Hügel weiß zwar nicht, wann und wo sie gefeuert werden, aber er kann darauf reagieren.
Abgesehen davon können aber in der Widget-Klasse nach Belieben weitere Funktionen und Eventhandler definiert werden. Dabei steht die komplette Bandbreite des ArcGIS API for JavaScript [iii] und des Dojo Toolkits [iv] zur Verfügung. Auch externe JavaScript Bibliotheken lassen sich problemlos einbinden.
Einbinden in den Web AppBuilder
Wir haben nun eine, mit Hilfe des Web AppBuilder erstellte, Anwendung um eigenen Code erweitert. Haben wir den Builder nur als Startpunkt verwendet um möglichst schnell und einfach eine WebApp zu erstellen, sind wir an dieser Stelle fertig. Soll unser Funktionsbaustein aber auch in anderen Anwendungen wiederverwendet werden können, müssen wir das Widget in das Unterverzeichnis „client\stemapp\widgets“ des Web AppBuilder kopieren. Dabei ist es wichtig die Datei „manifest.json“ korrekt zu pflegen, denn daraus liest der Builder die Attribute des Widgets.
Los geht’s
Mit diesem Wissen können Sie loslegen und Ihr eigenes Widget entwickeln. Jetzt brauchen Sie nur noch die passende Idee… Sollten Sie noch keinen konkreten Anwendungsfall haben, sehen Sie sich doch einmal im Internet nach Datenquellen um! Es gibt viele Webseiten, die RSS-Feeds oder APIs anbieten, über die sich Objekte mit Geoinformationen abrufen lassen. Je aussagekräftiger die Attributdaten, desto spannendere Geschichten lassen sich stricken, indem man sie verknüpft, filtert, auf der Benutzeroberfläche präsentiert und den User damit interagieren lässt.
Web AppBuilder for ArcGIS ist derzeit als Public Beta (Version 2) verfügbar. Dabei handelt es sich um eine Developer Edition, die auf eigener Hardware läuft. Nach der Registrierung auf http://betacommunity.esri.com erhält man den AppBuilder mit einer ausführlichen Dokumentation. In dieser ist auch ein umfangreicher Developer Guide enthalten.
Christine Brunner, Niklas Köhn, Esri Germany
i18n: Kurzform für „internationalization“: 18 Buchstaben zwischen „i“ und „n“
[ii] nls: Kurzform für „National Language Support“
[iii] Eine wichtige Anlaufstelle für Entwickler mit detaillierten Informationen über die Verwendung aller Klassen finden Sie in der API-Referenz: http://developers.arcgis.com/javascript
[iv] Auch hier gibt es API-Referenz für Entwickler: http://dojotoolkit.org