BrandenburgViewer - Entwicklerdokumentation
Benötigte Bibliotheken
-
ExtJs 6.2.0 (http://sencha.com)
-
OpenLayers 3.18.2 (https://github.com/openlayers/ol3/releases/tag/v3.18.2)
-
proj4js 2.3.15 (https://github.com/proj4js/proj4js/releases/tag/2.3.15)
-
https://github.com/mapbox/csv2geojson/releases/tag/v5.0.2
- Für die Verwendung im Browser: https://npmcdn.com/csv2geojson@5.0.2/csv2geojson.js
-
https://github.com/calvinmetcalf/shapefile-js/releases/tag/v3.3.2
-
https://github.com/mapbox/shp-write/releases/tag/v0.3.2
- Für die Verwendung im Browser: https://unpkg.com/shp-write@0.3.2/shpwrite.js
Die benötigten Bibliotheken sind bereits inkludiert und liegen unter:
resources/css/openlayers.css
resources/lib/ol3/ol.js
resources/lib/ol3/ol.css
resources/lib/proj4js/proj4.js
resources/lib/csv2geojson.js
resources/lib/FileSaver.js
resources/lib/shp.js
resources/lib/shpwrite.js
Weitere Hinweise zu den inkludierten Bibliotheken und deren Lizenzen finden sich unter licenses/README.md.
Compiler und Minifier
- Sencha Cmd 6.2 (https://www.sencha.com/products/extjs/cmd-download/)
Installationsanleitung
Diese Installationsanleitung geht von einem installierten und funktionierenden Sencha Cmd
aus
und einem entpackten Sencha Framework 6.2.0 (bsp. in /path/to/ext-6.2.0
) aus.
Repository clonen
Zunächst muss das Repository in ein gewünschtes Verzeichnis geclont werden:
git clone https://git.geobasis-bb.de/lgb-externe-softwareprojekte/bb-viewer.git
Initialisieren und Generierung der Anwendung
Im geclonten Verzeichnis muss der Sencha Workspace zum Initialisieren der Anwendung erzeugt werden:
sencha workspace init --add-framework ext=/path/to/ext-6.2.0
workspace init
stellt sicher, dass das aktuelle Verzeichnis ein (oder ein
Teil eines) Sencha Cmd
-Workspace ist. Die Option --add-framework ext=/path/to/ext-6.2.0
kopiert das Framework in das Verzeichnis ext
im BrandenburgViewer-mobil
-Ordner.
Alternativ kann das Framework auch verlinkt eingebunden werden.
ln -s /path/to/extjs-6.2.0 ext
sencha workspace init --add-framework ext=./ext
Einbinden des Elmasse-Bundles als Sencha Cmd package:
cd packages/local
sencha generate package elmasse-bundle
cd ../..
Mit diesem Befehl wird das Elmasse-Bundle als Sencha Cmd package initialisiert, sodass es durch Sencha Cmd in die Anwendung eingebunden werden kann.
Generieren der Applikation mit sencha cmd:
sencha app install
sencha app install
stellt sicher, dass sich eine unvollständige Sencha Cmd
-Anwendung in einem lauffähigen Zustand befindet. Zum Beispiel können Sie
einen sehr einfachen Anwendungsordner nehmen, diesen auf Ihren Rechner legen und
diesen Befehl ausführen, um eine vollständige Sencha Cmd-Infrastruktur
zu erstellen.
Hinweis: Ihre Anwendung wird erst dann vollständig sein, wenn Sie diese mit Hilfe von
sencha app build
bauen.
Dieser Befehl analysiert die Verzeichnisstruktur gemäß dem extjs6- Framework und erstellt/ passt folgende Dateien auf das lokale Dateisystem und die derzeit benutzten Klassen an:
bootstrap.js
bootstrap.css
classic.json
classic.jsonp
modern.json
modern.jsonp
Die Dateien können auch ohne Sencha Cmd
manuell angepasst werden. (TODO:
Standardkonfiguration ins Repository. Status von bootstrap.js
klären)
Damit das Produkt lauffähig ist und über die index.html aufrufbar ist, muss noch die Konfigurationsdatei resources/config/config.json erstellt (bzw. angepasst) werden.
Hinweise auf die Konfigurationsmöglichkeiten befinden sich in resources/config/config-example_DE.txt.
Danach ist das Produkt lauffähig und direkt über die Datei index.html aufrufbar.
Erzeugen einer produktiven Version
Zum produktiven Einsatz empfiehlt es sich, die Applikation mit Hilfe von
Sencha Cmd
weiter zu kompilieren und zu minifizieren.
cd /path/to/repository
sencha app build production
Anschließend findet sich im Unterverzeichnis build/production
eine
minifizierte Version mit allen benötigten Klassen und Bibliotheken, die als
komplettes Verzeichnis direkt und standalone benutzt werden kann.
Erzeugen von individuellen Builds
Das Repository dient zur Organisation aller VIEWER Ausprägungen die auf dem Quellcode des BrandenburgViewer basieren. Allerdings benötigen die einzelnen Ausprägungen mit unter individuelle Konfigurationen (bspw. Styledateien). In der app.json können die individuellen builds hinterlegt sowie konfiguriert werden.
...
"builds": {
"eks-desktop": {
"toolkit": "classic",
"name": "eks",
"theme": "theme-neptune",
"css": [{
"path": "https://style.brandenburg.de/2_2/css/vendors/font-awesome.min.css",
"remote": true
}, {
"path": "resources/css/ext-theme-neptune-all-red-debug.css"
}, {
"path": "resources/css/custom-eks.css"
}],
"sass": {
"generated": {
"var": "classic/sass/save.scss",
"src": "classic/sass/save"
}
}
}, ...
Dazu folgende Punkte:
- Es wurde der Ordner builds hinzugefügt. In diesem können konfigurationsspezifische Ressourcen abgelegt werden. Bspw. liegt die custom-eks.css jetzt unter builds/eks/resources/css/custom-eks.css. Beim Bau der Viewer-Varianten werden diese spezifischen Resourcen-Ordner mit dem gemeinsamen Resourcen-Ordner (resources) zusammengeführt.
- Das Einbinden von konfigurationsspezifischen css-Dateien geschieht nicht mehr über die index.html sondern über die app.json in der entsprechenden Build-Konfiguration. Dies gilt auch für die extern nachgeladene font-awesome.min.css.
- In der "Development-Variante" wird standardmäßig der BBViewer gestartet.
- Die Config-Dateien für alle Varianten werden wie zuvor aus dem Ordner resources/config/ geladen. Der Viewer erwartet dabei einen Dateinamen entsprechend seines Build-Namens, also etwa resources/config/eks.json für die EKS-Variante.
- Die Application.js, also der Haupteinstiegspunkt der Anwendung, liegt im Order builds/{App.name}/resources/classic/src.
Die angegebenen relativen Pfade (resources/css/custom-eks.css) beziehen sich dabei auf den Eingangspunkt der individuellen name der build Version (bspw. Repo/builds/eks).
Produktiv gebaut werden die builds mittels sencha app build app.name:
cd /path/to/repository
sencha app build eks-desktop
bzw.
sencha app build bbviewer-desktop
resources
Erstellung und Umgang von HTML-Dokumenten im Ordner HTML-Dokumente im Ordner resources müssen wohlgeformte und valide
XHTML-Dokumente sein, also den Syntaxregeln von XML entsprechen. Zusätzlich
sollten zum Beispiel Unicode-Entitäten anstatt HTML-Entitäten genutzten werden.
Also sollte ©
anstatt ©
für ©-Symbol verwendet werden. Für die
Überprüfung der Dokumente kann bspw.
xmllint verwendet werden. Denn die entsprechende
Fehlermeldung in der Konsole der Browser-Entwicklerwerkzeuge ist meistens wenig
hilfreich.
Eine typische Fehlermeldung bei ungültigen oder fehlerhaften HTML-Dokumente in
der Konsole eines Browser-Entwicklerwerkzeuges ist bspw: XML Parsing Error: not well-formed
.
Hinweise zur Bereitstellung und Verwendung einer BRANDENBURGVIEWER-Bibliothek
Hinweise zur Bereitstellung und Verwendung einer BRANDENBURGVIEWER-Bibliothek finden Sie in der Datei LIBRARY.md.
Erzeugen einer nativen App für Android, iOS und Windows 8.1
Hinweise zum Erzeugen einer nativen App für Android, iOS und Windows 8.1 finden Sie in der Datei PACKAGING.md.
Modifizierter OpenLayers Build
Hinwiese zum Erstellen eines eigenen modifizierten OpenLayers Build finden Sie in der Datei patches/README.md.
Verwendung des Dokumentationstools
TODO