20. März 2019

Einführung

Das ist das Administratoren-Manual für placeit 3. Es wird während der Fertigstellung des Prototyps fortgeschrieben und soll wenigstens die wichtigsten Informationen enthalten, die für das Aufsetzen und den Betrieb einer placeit-Instanz erforderlich sind.

Eine placeit 3-Instanz ist technisch eine One Page Webapp, die aus einer Reihe von Javascript- Files und einem sehr dünnen PHP-Servicelayer besteht. In der derzeitigen Form wird (noch) keine Datenbank verwendet. Alle File-Objekte sind als JSON-Objekte angelegt.

Installation einer Instanz

Eine placeit 3-Instanz ist im Filesystem folgendermaßen angelegt: Im Document Root der Instanz (Instanz und Anwendung werden bisweilen synonym verwendet, wenn keine Unterscheidung erforderlich und keine Verwechselungsgefahr gegeben ist) befinden sich zwei Files, die vom Administrator zu editieren sind:

Im Directory /js/leaflet-backend befindet sich das CSS-File leaflet-exp.css, das sämtliche Style-Informationen beinhaltet.

Die globale Konfiguration

Das File configuration.json enhält die Konfigurationsparameter, die für eine Instanz angepasst werden können. Das sind die folgenden Parameter:
extent Ein Array aus vier numerischen Werten
center Das Zentrum der Karte in geographischen Koordinaten (Länge, Breite)
image Pfad zu dem PNG, das das Image Layer enthält (s. Anm. unter Konfiguration)
Die Werte sollten nur bei Erzeugen der Instanz gesetzt werden.

Komponenten einer Instanz

In diesem Abschnitt werden die Funktionalitäten des Frontends beschrieben. Gegenüber der Version 2 sind einige markante Designänderungen vorgenommen worden.

Rechts ist an Stelle des alten, über der Karte liegenden, Navigationspanels nun ein fester Navigationsbereich entstanden, der aus drei vertikal unter einander angeordneten Teilen besteht:

Am oberen Rand ist eine Menüzeile vorhanden, die sowohl dieses Manual enthält als auch Platz für eine Reihe von Bedienelementen im rechten Teil bietet. Derzeit sind drei Menübereiche vorhanden: Den größten Teil nimmt weiterhin die eigentlich Karte ein, die – derzeit noch im Code festgelegt – 70% der verfügbaren Breite nutzt ( das wird in DOMMasterView.js definiert – leider gibt es noch eine alte Abhängigkeit in PlaceitMapControl.js).

Beschreibung der einzelnen Bereiche

Im folgenden werden die drei Bereich der Navigation Area etwas genauer beschrieben, um den Vergleich zu den Funktionalitäten der Version 2 zu ermöglichen.

Kategorien-Bereich

Im Kategorien-Bereich werden die vorhandenn Kategorien als kleine quadratische Icons (vergleichbar twa mit Apps auf mobilen Geräten) dargestellt. Das Klicken auf eine Kategorie filtert die Datensätze im Datensatz-Bereich so, dass nur Geoitems der betreffenden Kategorie angezeigt werden. Erneutes Klicken hebt den Filer wieder auf.
Die Funktionalität ist noch nicht voll implementiert: Derzeit funktioniert zwar die Addition von zwei oder mehr Filtern, jedoch führt das Aufheben des ersten Filters bereits zur Rücknahme der gesamten Einschränkung.

Die Darstellung des Kategorien-Bereiches kann mittels CSS verändert werden. Die relevanten Styles sind im Bereich mit der Bezeichnung Categories zusammengefasst. Von Bedeutung ist hier insbesondere das Layout der Kategorien-Icons. Eine Änderung kann beispielsweise so aussehen:

Die Icons sind hier mit automatischer Weite dargestellt, was eine ganz andere Anmutung ergibt.

Datensatz-Bereich

Der Datensatz-Bereich enthält, anders als in Version 2, alle Datensätze der Instanz in einer scrollbaren vertikalen Liste. Jeder Datensatz ist als kleines längliches Kärtchen dargestellt. Im Augenblick werden auf den Kärtchen im Code festgelegte Informationen des jeweiligen Geoitems dargestellt (die Festlegung erfolgt DOMItemView.js). Durch Klicken wird ein Geoitem aktiv: Die geographischen Informationen werden auf der Karte, die textuellen und visuellen Informationen im Slide-Bereich dargestellt. Details zu den Geoitems werden unten aufgeführt.

Analog zur Darstellung der Kategorien kann auch die Darstellung der Geoitems im CSS verändert werden. Der Bereich List of geoitems enthält die entsprechenden Style-Klassen.

Die Bedienmimik für Geoitems benötigt folgende Begriffe:

Damit ergibt sich Folgendes:

Ein anfangs passive Geoitem wird durch einmaliges Klicken active und expanded; die Slidelist wird angezeigt.

Wenn ein weiteres Geoitem angeklickt wird, so bleibt das erste Geoitem active, es entfällt aber die Eigenschaft expanded. Das neu angeklickte Geoitem wird active und expanded.

Wird nun auf das erste angeklickte Geoitem erneut geklickt, so wechselt es in den Status expanded und das zweite Geoitem verliert diesen Zustand.

Ein Geoitem, das sowohl active als auch expanded ist, wird durch Anklicken passive, wird also von der Karte entfernt. Die im unteren Bereich angezeigte Slidelist wird ebenfalls entfernt und durch eine Slidelist ersetzt, die zu einem noch vorhandenen aktiven Geoitem gehört.

Es ist auch möglich, die Tooltips auf der Karte anzuklicken, um ein aktives Geoitem in den Zustand expanded zuversetzen.

Derzeit führt – in gewisser Weise konsequent – das Klicken auf das Tooltip eines Geoitem, das active, expanded ist, dazu, dass dieses Geoitem passive wird. Das sollte wohl noch geändert werden.

Slidelist-Bereich

Der unterste Bereich in der Navigation Area ist der Slidelist-Bereich. Er beinhaltet die textuellen und visuellen Informationen zu einem Geoitem, das expanded ist. Diese Informationen sind, daher der Name, in Form eine Folge von Folien (oder Tafeln) dargestellt. Ein Bedienelement rechts dient zum Weiterblättern.

Wie im folgenden Screenshot dargestellt, enthält die Slidelist im Titelbereich rechts ein Bedienelement:

Durch Klicken auf das Element wechselt die Ansicht in die Detailansicht für das Geoitem. Das ist eine grundlegend neue Funktionalität von placeit 3. Dazu wird weiter unten mehr gesagt.

Vergleich mit der Version 2

Die Version 2 von placeit (aka CRIA Maps 2) stellte teilweise abweichende Funktionalitäten bereit. Diese Abweichungen werden hier im Folgenden besprochen. Soweit nicht anders vermerkt, gelten diese Abweichungen als gewollt und werden nicht nachimplementiert.

Kategorien und Tags

Die Version 2 kannte sowohl Kategorien als auch Tags. Geoitems konnten in ein oder mehreren Kategorien enhalten sein und beliebig viele Tags zugewiesen bekommen. Während Kategorien die Grobstruktur für das Navigationspanel bereitstellten, dienten die Tags zur Gruppierung von Geoitems und zur Steuerung der gleichzeitigen Darstellung mehrerer Items auf der Karte (vgl. den Screenshot):

Die Möglichkeit dieser letztgenannten Gruppierung ist jetzt weggefallen. Möglich ist es, dass mehere Punkte oder Streckenzüge in einem Geoitem zusammengefasst werden. Diese werden dann aber als ein Geoitem behandelt und nicht als eine Gruppe von Geoitems.

Ist das ein problematischer Verlust: Die Gruppierung von Geoitems mittels Tags war eingeführt worden, um in großen Datenbeständen von vielen hundert Datensätzen eine leichgewichtige Struktur einführen zu können. Der Use Case war immer der, dass in einer Kategorie, die die grobe Struktur der Informationen vorgibt (beispielsweise "Essen und Trinken") auf diese Weise alle Datensäzte für italienische Restaurants oder für preiswerte Küche gleichzeitig auf der Karte angezeigt werden können.

Die Version 3 von placeit kann mehrere Geoitems gleichzeitig auf der Karte darstellen, wenn diese in einer Kategorie liegen (s.u. – Struktur der Datensätze). Auf diese Weise kann das auf der Übersichtskarte geschehen. Alternativ können Datensätze als abhängig von einem Masterdatensatz gekennzeichnet werden. Sie werden dann in der Detailkarte zu dem betreffenden Master angezeigt.

Was nicht mehr geht, ist das schnelle Anzeigen von vielen von einander unabhängigen Datensätzen auf einer Karte durch Anklicken mehrerer Tags in mehreren Kategorien; das geht natürlich nach wie vor noch, wenn man alle gewünschten Datensätze einzeln auswählt. Man kann auch entsprechende Kategorien bilden, die auf diese Weise die Funktion der alten Tags übernehmen.

Generell kann man sagen, dass die Kategorien leichtgewichtiger geworden sind und die Tags durch die Detailkarten ersetzt worden sind.

Darstellung im Navigationspanel

Das Navigationspanel der Version 2 ist so aufgebaut, dass jeweils einzelne Kategorien dargestellt werden können. In der Kategorie werden primär Tags dargestellt; die Darstellung einzelner Geoitems ist nachträglich hinzugefügt worden und war immer nur hilfsweise gedacht.

In Version 3 ist das grundlegend geändert worden. Ausgehend von der Beobachtung, dass in der Regel nicht so viele Datensätze in der Übersicht dargestellt werden müssen, werden diese jetzt dem Benutzer immer offen angeboten. Die Idee dabei ist, dass das Scrollen auf modernen Geruaten sehr einfach ist und auch lange Listen leicht durchscrollt werden können (insbesondere auch auf mobilen Geräten).

Die Filterung findet in Version 3 in der umgekehrten Richtung statt: Die Katgorien dienen der Einschränkung der angezeigten Geoitems und sind eher ein Mittelding zwischen alter Kategorie und Tag (siehe die Bemerkung oben).

Informationsdarstellung

Eine weitere massive Änderung hat die Darstellung der textuellen und visuellen Informationen zu den Geoitems in Version 3 erfahren: Beide Veränderungen haben ihren Grund in Beobachtungen bei der Nutzung.

Alle Informationen zu einem Geoitem sind nach Anklicken direkt verfügbar: Die schrittweise Bereitstellung von Informationen zu einem Geoitem kann zu Irritation und Frustration beim Benutzer führen: Er sieht nach der initialen Auswahl zunächst nur die Nadel auf der Karte. Dann muss er auf die Nadel klicken, um die erste textuelle oder visuelle Information zu bekommen. Nun kann er ein weiteres Mal klicken und erhält ein weiteres Fenster (auf der Karte) mit Informationen.

Hier sind mehere Unfallmöglichkeiten gegeben: Zunächst kann der Benutzer nicht auf die Idee kommen zu klicken; dann wird er gewisse Informationen nicht erhalten. Wenn das Geoitem nicht viel Information enthält, kann das umgekehrt zu Frustration beim Benutzer führen.

Der obige Screenshot zeigt diese Situation am Beispiel des Putting Greens im Golfclub Arosa: Insgesamt dreimaliges Klicken liefert ein im wesentlichen leeres Fenster ohne Information. Im Gegensatz dazu liefert einmaliges Klicken bei placeit 3 bereits die gesamte Information:

Selbst in dem hier gewählten Fall, dass das Geoitem nicht viel Information zu bieten hat, ist das nicht so schlimm, denn der Benutzer sieht das auf einen Blick und kann sich anderen Informationen zuwenden.

Die Informationen werden nicht auf der Karte dargestellt: Die ursprüngliche Idee bei CRIA Maps / placeit 2 war, dass das direkte Einblenden von Informationen in die Karte eine engere Interaktion ermöglichte. Das wird auch durch das Anklicken von Nadeln auf der Karte verdeutlicht. Der Nachteil dieses Design ist, dass bei angemessener Darstellung von visuellen und textuellen Informationen immer ein gewisser (auch großer) Teil der Karte verdeckt wird. Das kann auch lästig werden, wenn man dann die Information erst wieder schließen muss, um sie später erneut zu öffnen.

Das Verfahren von placeit 3 ist dem gegenüber klar: Die Karte wird nur dann beeinträchtigt, wenn der Ersteller der Instanz das explizit entschieden hat, indem er ein Bild zu einem Geoitem in der Karte anzeigen lässt. Sonst werden nur Icons oder Streckenzüge dargestellt.

Design im allgemeinen

Das Design des User Interfaces war insgesamt in die Jahre gekommen. Daher ist die optische Aufbereitung aufgefrischt worden. Die Nutzung von CSS zur Gestaltung ermöglicht – in Grenzen – die Anpassung des Look and Feel durch den Administrator der Instanz.

Struktur der Datenhaltung

Derzeit läuft eine placeit 3-Instanz ohne Datenbank. Die gesamte Datenhaltung erfolgt im Filesystem und nutzt gewöhnliche Files. Es sind folgende Sorten von Datenobjekten zu unterscheiden: In den folgenden Abschnitten werden die Objekte einzeln beschrieben.

Geoitems

Die Datenstruktur für die Datensätze findet in den Geoitems statt.

Der Begriff ist zu Beginn der Produktentwicklung vor vielen Jahren aufgekommen und seitdem tradiert worden. Immerhin bringt er zum Ausdruck, dass die Daten irgendeinen geographischen Bezug haben.

Technisch handelt es sich um JSON-Objekte, die (derzeit) in Textfiles angelegt sind (s.o. zur Struktur des Filesystems). Ein JSON-Objekt der hier verwendeten Form besteht aus Properties, die auch als Felder bezeichnet werden und eventuell verschachtelt sein können. Das folgende Beispiel stellt ein ganz einfaches JSON-Objekt mit genau einem Feld dar:

      {
        "Vorname" : "otto"
      }
      
Man beachte, dass das Objekt mit geschweiften Klammern beginnt und endet. Das Feld mit dem Namen Vorname ist von doppelten Anführungszeichen umgeben und durch einen Doppelpunkt von dem Wert (otto), den das Feld hat, getrennt. Wenn ein JSON-Objekt mehr als ein Feld besitzt, so werden die Felder durch Kommata getrennt. Wenn der Wert eines Feldes ein Array ist, so wird das so notiert:
      {
        "Hobbies" : ["Triathlon", "Reiten", "Golf"]
      }
      
Die eckigen Klammern zeigen das Array an, nur die eigentlichen Werte werden wiederum in doppelte Anführungszeichen gesetzt.

Damit ein Geoitem vom Backend-Service berücksichtigt wird, muss es in dem (konfigurierten) Directory liegen und die Endung .json tragen. Der folgende Codeauszug stellt die Struktur dar:

      {
        "type": "feature",
        "properties": {
          "id": "...",
          "title": "...",
          "info": "...",
          "priority" : "...",
          "initial_display" : "...",
          "slides": ["...", [...]],
          "dependency": "...",
          "dependent": "true",
          "dependencies": ["..."],
          "map": {
            "center": ["...","..."],
            "resolution": "..."
          }
        },
        "geometry": {
          "type": "...",
          "coordinates": [...]
        }
      }
      

Strukturell handelt es sich um ein GeoJSON-Objekt. Im Folgenden werden die einzelnen Properties beschrieben.

Generell ist zu beachten, dass alle Inhalte immer in Anführungszeichen gesezt werden müssen. Am Schluss des Abschnittes gibt es Beispiele, die die Struktur erläutern.

priority

Wenn dieses Feld existiert und auf true gesetzt ist, dann wird das Geoitem in der Listendarstellung auf active und expanded gesetzt.

initial_display

Wenn dieses Feld existiert und auf true gesetzt ist, dann wird das Geoitem in der Listendarstellung auf active gesetzt.
Wenn kein Geoitem auf priority gesetzt ist, so wird das letzte Geoitem in der Liste der initial darzustellenden Items auf expanded gesetzt. Die Reihenfolge, in der die Items abgearbeitet werden, ist nicht festgelegt.

image

Pfad zu einem JPG oder PNG, das auf der Karte selbst angezeigt wird, wenn das Geoitem expanded ist.

text_offset

Das Feld ermöglicht eine Änderung der Positionierung des Info-Overlays zu einem Feature auf der Karte. Falls das Feld nicht vorhanden ist, so wird das Overlay oberhalb des Bildes angezeigt, wenn ein Bild vorhanden ist, und unterhalb der Default-Nadel sonst.

dependency

Das ist eine schlechte Bezeichnung. Eigentlich müsste es master heißen, denn es signalisiert, dass das Geoitem abhängige Datensätze hat, wenn das Feld auf true gesetzt ist.

dependent

Wenn dieses Feld existiert und auf true gesetzt ist, dann wird das Geoitem nur in einer Detailansicht angzeigt. Die Anzeige wird dann von dem betreffenden Master-Item kontrolliert (siehe Anmerkung oben).

dependencies

Das ist ein Array von Feldern. Jeder Array-Eintrag enthält die Id eines Geoitems, das nur in der von diesem Geoitem kontrollierten Detailansicht angezeigt wird.

master

Wenn das Feld vorhanden ist, enthält es die Id desjenigen (Master-)Items, in dessen Detailansicht dieses Geoitem angezeigt werden soll. Es wird sonst an keiner Stelle angezeigt.
Hier ist noch eine kleine Einschränkung, die entfallen muss: Bislang ist das Feld skalar, also kann es nur einen Master geben. Das sollte so geändert werden, dass das Feld master ein Array von Id's ist.

map

Das Feld wird derzeit nur für Geoitems verwendet, die Master-Items sind. Dann gibt es das Zentrum und die Auflösung der Detailkarte an.
Derzeit werden noch keine Informationen über die Kartenlayers konfigurativ abgelegt; das müsste aber passieren.

geometry

Das ist die Geometrie des Geoitems. Derzeit werden die folgenden Geometrietypen unterstützt: Point
      "geometry": {
        "type": "Point",
        "coordinates": ["...", "..."]
       }
      
Die beiden Koordinaten in coordinates sind wirkliche Geo-Koordinaten.

MultiPoint

      "geometry": {
        "type": "Point",
        "coordinates": [["...", "..."], ["...", "..."], ...]
       }
      
Die Koordinaten der einzelnen Punkte sind als Sub-Arrays in dem coordinates-Array abgelegt.

LineString

      "geometry": {
        "type": "LineString",
        "coordinates": [["...", "..."], ["...", "..."], ...]
      }
      
Das Format des Koordinaten-Arrays entspricht dem des MultiPoint. Durch die andere Typenbezeichnung werden die Koordinaten anders interpretiert.

Polygon

      "geometry": {
        "type": "Polygon",
        "coordinates": [["...", "..."], ["...", "..."], ...]
      }
      
Das Format des Koordinaten-Arrays entspricht dem des MultiPoint oder LineString. Das erste und das letzte Koordinatenpaar müssen identisch sein, damit das Polygon geschlossen wird.

Beispiele

Im Folgenden werden einige Geoitems vorgestellt, die für die Instanz Arosa Golf genutzt werden. Sie illustrieren die Möglichkeiten von aghängigen und unabhängigen Geoitems.

Beispiel 1: Ein einfaches Geoitem
Das folgende Geoitem ist ein unabhängiges Geoitem mit einer Reihe von Eigenschaften, die im Anschluss an den Code erklärt werden:
      {
        "type": "feature",
        "properties": {
          "id": "1000",
          "title": "Clubhaus",
          "info": "Das Clubhaus mit Sekretariat",
          "categories": ["Service"],
          "category": "Service",
          "initial_display" : "true",
          "image": "/bilder/clubhaus_klein.jpg",
          "slides": ["<img src=\"/bilder/clubhaus.jpg\" class=\"details-image\">",\n
             "Das gemütliche Clubhaus",\n
             "<a href=\"http://hofmaran.ch/golfhuus\" target=\"_blank\">Zur Website<a>"\n
           ]
        },
        "geometry": {
          "type": "Point",
          "coordinates": ["9.681916236877441", "46.79134830043571"]
        }
      }
      
Die ersten Properties (id, title, info) müssen nicht erklärt werden. Das Property categories enthält ein Array ([...]) mit genau einem Eintrag, nämlich dem Text "Service". Das ist die Katgorie, der das Geoitem zugeordnet ist.
Das Ferld initial_display ist auf true gesetzt und zeigt an, dass das Geoitem beim Laden der Karte auf active gesetzt werden soll.
Weiterhin enthält das Geoitem ein JPG (clubhaus_klein.jpg), das auf der Karte angezeigt wird, wenn das Geoitem expanded ist.
Das Array slides enthält exemplarisch drei Slides, die hier der Übersichtlichkeit halber in separaten Zeilen dargestellt sind. Damit endet der properties-Teil des Geoitems.
Der Teil geometry des Geoitems ist einfach; es handelt sich um einen Punkt ("type": "Point") mit den zwei erforderlichen Koordinaten (Längengrad vor Breitengrad).

Beispiel 2: Ein Streckenzug
Das zweite Geoitem zeigt einen Streckenzug und ist ansonsten weitestgehend vergleichbar mit dem Punkt aus dem ersten Beispiel:
      {
        "type": "feature",
        "properties": {
          "id": "606",
          "title": "Ausgrenze",
          "info": "Aus rechts",
          "categories": ["Herren","Damen"],
          "slides": [""],
        },
        "geometry": {
          "type": "LineString",
          "coordinates": [["9.679871040033616","46.79373727991225"],\n
                          ["9.680962169056095","46.79374755995005"],\n
                          ["9.68157280089436","46.79373727991225"],\n
                          ["9.68187311163449","46.79361049261797"],\n
                          ["9.68191815824551","46.79346314484667"]]
        }
      }
      
Der konzeptionell einzige Unterschied ist im Geometrie-Teil des Geoitems zu finden. Es ahndelt sich um einen LineString, was durch "type": "LineString" festgelegt wird. Man beachte das große S bei LineString – JSON ist da sehr empfindlich. Die Koordinaten sind insgesamt fünf Punkte, die den Streckenzug aufspannen. Die Zeilenumbrüche dienen wiederum nur der Lesbarkeit und dürfen in einem File nicht vorkommen.

Beispiel 3: Ein Master-Geoitem
Das dritte Beispiel zeigt ein Master-Item:
      {
        "type": "feature",
        "properties": {
          "id": "3",
          "title": "Loch 3",
          "info": "Par 4",
          "categories": ["Platz", "Par 4"],
          "slides": [""],
          "dependency": "true",
          "dependencies": ["301"],
          "map": {
            "center": ["9.684974011655232","1599612"],
            "resolution": "18.0"
          }
        },
        "geometry": {
          "type": "LineString",
          "coordinates": [["9.687000832608542","46.79465521448972"], \n
                          ["9.684481058236587","46.794965788700495"], \n
                          ["9.683133585310406","46.795101087796155"]]
        }
      }
      
Ein Blick auf die Geometrie-Informationen zeigt, dass es sich bei dem Geoitem um einen Streckenzug (LineString) handelt. Bis auf die Properties dependency und dependencies sind die allgemeinen Felder bereits wohlbekannt.
Das Feld dependency ist auf true gesetzt und zeigt an, dass es abhängige Datensätze gibt; das folgende Feld dependencies ist ein Array, das in diesem Fall nur einen Eintrag hat ("301"). Dieser Wert ist die Id des abhängigen Geoitems.
Von großer Bedeutung ist das Feld map, das eine eigene Substruktur mit den Feldern center und resolution hat. Dieses Property gibt an, dass die Detailkarte mit der initialen Auflösung 18.0 und dem geographischen Zentrum bei (9,68497 ; 46.794879) angezeigt werden soll.

Beispiel 4: Ein abhängiges Geoitem
Das letzte Beispiel zeigt nun ein abhängiges Geoitem, das nur auf einer Detailansicht dargestellt werden soll:
      {
        "type": "feature",
        "properties": {
          "id": "301",
          "title": "Abschlag Gelb",
          "info": "285 Meter",
          "slides": [""],
          "dependent": "true",
          "master": "3"
        },
        "geometry": {
          "type": "Point",
          "coordinates": ["9.687000832608542","46.79465521448972"]
        }
      }
      
In diesem Beispiel ist nur eine Besonderheit zu beobachten: Es sind die beiden Felder dependent und master gesetzt. Das erste Feld ist "true" und zeigt an, dass es sich um ein Geoitem handelt, das nur in der Detailansicht zu einem anderen Geoitem angezeigt werden soll. Das Feld master gibt die Id des zugehörigen Master-Items an (das soll noch geändert werden – siehe dazu die Anmerkung oben im Abschnitt zu den einzelnen Feldern).

Kategorien-Informationen

Die Struktur der Datei für die Kategorien-Information (categories.json im Document Root) ist einfach und wird im folgenden Codeauszug dargestellt:

      {
        "Platz": {
          "title": "Platz",
          "order": "1",
          "active": ["1", "2"],
          "color": "#42eef4"
        },
        "Par 3": {
          "title": "Par 3",
          "order": "2",
          "active": "all",
          "color": "#fc8719"
        },
        ...
      }
      

Es handelt sich um ein einfaches JSON-Objekt, das als primären Schlüssel den Namen der Kategorie und als Properties (derzeit) title, order, active und color enthält.
Die Property title wird in der Anzeige der Kategorie verwendet; sinnvoll ist ein kurzer String.
Die Property order wird in eine CSS-Anweisung für ein Flex-Item umgewandelt. Wenn es zu einer Kategorie keine Ordnungszahl in der Konfiguration gibt, wird die Style-Anweisung nicht gegeben.
Die Property active enthält ein Array mit Ids von Geoitems, die beim Anklicken der Kategorie aktiviert werden sollen. Die betreffenden Geoitems werden auf der Karte als Feature dargestellt und in der Item-Liste als active dargestellt.

Die aktivierten Geoitems bleiben auch nach Abschalten der betreffenden Kategorie aktiv. Das entspricht dem Verhalten mehrerer ausgewählter Kategorien in der Version 2.

Die Property color legt die Hintergrundfarbe der Kategorie in der Kategorienanzeige fest. Die Sättigung der Farbe wird bei passiver (nicht ausgewählter) Kategorie reduziert. Eine ausgewählte Kategorie wird mit der Farbe in voller Sättigung hinterlegt. Die Informations-Overlays zu den Geoitems werden mit der gleichen Farbe hinterlegt.
Wenn ein Geoitem mehr als einer Kategorie zugehörig ist, so wird für die Farbauswahl des Info-Overlays die erste Kategorie herangezogen.

Konfiguration

Derzeit existiert nur ein rudimentäres Konfigurationsfile namens configuration.json, in dem die zu Beginn beschriebenen Informationen zur Karte und dem Image Layer enthalten sind. Das folgende Beispiel zeigt die Konfigurationsdatei für die Instanz Golf Arosa:

      {
      "extent"    : ["0","0","1453","1532"],
      "image"     : "/golf.png",
      "center"    : ["9.683724419579253","46.79211418897583"],
      "resolution": "16.5",
      "geoitems"  : "/geoitems",
      "images"    : "/bilder",
      "videos"    : "/videos",
      "categories": "/categories.json",
      "initial"   : "Intro""
      }
      

Das Array, das als Wert für das Feld extent angegeben wird, beschreibt die Geometrie des Bildes für das Image Layer. Wenn kein Image Layer verwendet wird, können die Wert so bleiben.

Der Code behandelt das Weglassen dieser Konfigurationseinstellung noch nicht robust. Das muss noch geändert werden, wenn das Handling des Image Layers später noch einmal angefasst wird.

Der Pfad, der unter image angegeben wird, verweist auf das Bild für das Image Layer. Es ist der absolute Pfad relativ zum Document Root der Instanz.
Der Pfad kann ein leerer String sein, dann wird kein Image Layer angezeigt.

Der Code versucht intern, ein Image Layer zu erzeugen, findet aber kein Image und scheitert daher ohne weitere Hinweise; das muss eigentlich auch noch geändert werden.

Unter center werden die Geokoordinaten des gewünschten Kartenzentrums in der bekannten Reihenfolge (Länge, Breite) angegeben.

Unter resolution wird die initiale Auflösung (Zoom) der Karte in der bekannten Form in Werten zwischen 10.0 und 16.5 angegeben.

Die nächsten vier Einträge werden derzeit noch nicht ausgewertet.

Das Feld initial legt die Kategorie fest, die beim Laden der Instanz aktiv sein soll. Wenn es zu dieser Katgorie ein Geoitem gibt, das ebenfalls aktiv sein soll, so wird es angezeigt.

Es ist anzustreben, dass mindestens folgende Dinge dort noch untergebracht werden:

Grundlegende Funktionalität

In diesem Kapitel wird die eigentliche Funktionalität von placeit 3 beschrieben. Die einzelnen Abschnitte befassen sich mit dem Aufbau einer Site, mit der Verwendung von globalen und Detail- Ansichten, mit Kategorien und der Nutzung der verschiedenen Eigenschaften von Geoitems.

Allgemeines

Eine typische placeit 3-Site besteht aus einer Reihe von Geoitems, die in Kategorien struktriert sind und Darstellungen in Form von Punkten, Streckenzügen oder Polygonen auf einer Karte haben. Jedes Geoitem verfügt über eine Reihe von Slides, auf denen Texte, Bilder oder Videos dargestellt werden können. Der folgende Screenshot zeigt eine typische Ansicht einer placeit-Site

Im Bild sind vier Bereiche markiert:

Diese vier Bereiche spielen zusmmen bei der Gestaltung und Nutzbarmachung von Informationen mit placeit.

Kategorien

Kategorien dienen der Strukturierung einer placeit-Site. Sie gruppieren die Geoitems in (nicht notwendig disjunkte) Klassen. In dem oben dargestellten Beispiel insgesamt acht Katgorien zu sehen. Das Auswählen einer Kategorie filtert die angezeigten Geoitems: Es werden nur solche Geoitems angezeigt, die in der ausgewählten Kategorie enthalten sind.

Das Auswählen einer Kategorie erfolgt durch Klicken auf das entsprechende Symbol. Abermaliges Klicken beendet die Filterung.

Wenn eine Kategorie ausgewählt ist, führt das Klicken auf eine andere Kategorie zum Wechsel des Filters auf die zuletzt ausgewählte Kategorie. Es werden also keine Filterungen addiert. Das dient dem Verständnis der Bedienung durch den Benutzer.

Geoitems

Geoitems enthalten die Daten, die in einer placeit-Site dargestellt werden. Sie bestehen aus den textuellen und visuellen Informationen, die in der Slidelist dargestellt werden, und den Informationen auf der Karte, dem sogenannten Feature.

Ein Geoitem kann mehrere Zustände annehmen: Es kann passive, active, collapsed oder expanded sein.

Das Geoitem ist active, wenn das zugehörige Feature auf der Karte angezeigt wird. Ein aktives Geoitem kann entweder collapsed oder expanded sein. Es ist expanded, wenn seine Slidelist angezeigt wird und collapsed andernfalls.

Das obige Bild zeigt ein Geoitem, das active und expanded ist. Der Zustand active wird durch den Schatten und den farbigen Hintergrund angezeigt. Der Zustand expanded wird durch die grüne Checkbox-Marierung rechts angezeigt.

Wird ein Geoitem angeklickt, das active und expanded ist, so wird es in den Zustand passive versetzt; sein Feature wird von der Karte entfernt, seine Slides aus der Slidelist.

Wird ein Geoitem angeklickt, das active und collapsed ist, so wird es in den Zustand active und expanded versetzt. Das Geoitem, das bisher expanded war, wird in den Zustand active und collapsed versetzt.

Slidelist

Die Slidelist stellt alle textuellen und visuellen Informationen zu einem Geoitem dar (vgl. oben). Die Informationen sind, daher der Name, als eine Folge von Seiten angeordnet, durch die der Benutzer der Reihe nach blättern kann. Ein entsprechendes Symbol rechts lädt dazu ein, wenn mehr als eine Seite vorhanden ist. Die einzelnen Seiten oder Slides können beliebige HTML-Inhalte enthalten.

Feature

Zu einem Geoitem gehört in der Regel ein Feature, das auf der Karte dargestellt wird. Features können Punkte, Streckenzüge oder Flächen sein.
Derzeit sind noch keine gemischten Features implementiert, die aus mehreren Typen von Darstellungen auf der Karte bestehen. Das ist aber notwendig, wenn die Funktionalität der Version 2 aufrecht erhalten werden soll, die zusammengesetzte Karteninformationen durch mehrere Geoitems mit dem gleichen Tag realisiert.

Zu den Möglichkeiten von Features wird im Folgenden mehr gesagt.

Globale Geoitems und ihre Verwendung

Die grundlegenden Bausteine einer placeit-Site sind die Geoitems. In der Version 2 waren alle Geoitems von einander unabhängig; das ist in der neuen Version geändert worden: Es gibt jetzt globale Geoitems und anhängige Geoitems, die im nächsten Abschnitt behandelt werden. Globale Geoitems verhalten sich weitgehend wie Geoitems in der Version 2.

Ein Geoitem besteht zunächst grob aus zwei Teilen, nämlich dem Informationsteil (auch Slidelist genannt) und dem Kartenteil (auch Feature genannt). Beide Teile werden weiter unten getrennt erläutert.

Ein Geoitem kann eine Reihe von Eigenschaften haben, die sein Verhalten auf der Site beeinflussen. Die wichtigsten Eigenschaften werden hier noch einmal aufgeführt; eine vollständige Liste findet sich weiter oben im Manual im Abschnitt Struktur der Datenhaltung.

Zunächst kann es sowohl auf den Informations- als auch auf den Kartenteil verzichten. Obligatorisch für ein Geoitem ist ausschließlich der Titel; das betreffende Feld trägt den Namen title.

Weiterhin kann ein Geoitem eine Eigenschaft erhalten, die seine Zugehörigkeit zu einer oder mehreren Kategorien festlegt. Es wird dann beim Filtern nach diesen Kategorien in der Liste aufgeführt. Das entsprechende Feld trägt den Namen categories und ist als Liste (Array) realisiert.

Weitere nützliche Eigenschaften sind initial_display und priority. Diese Eigenschaften steuern, ob ein Geoitem beim Laden der placeit-Site bereits aktiv ist und ob seine Informationen angezeigt werden (vgl. dazu oben Struktur der Datenhaltung).

Slidelist eines Geoitems

Die Slidelist des Geoitems enthält alle textuellen und visuellen Informationen, die der Benutzer über das Geoitem erfahren soll. Wie der Name andeutet, handelt es sich um eine Liste von Informationsobjekten, den Slides. Um eine möglichst flexible Nutzung zu ermöglichen, kann ein Slide nahezu beliebiges HTML enthalten.

Gegenüber der Version 2 ist die Trennung zwischen einer durchlaufenden Liste von Bildern und einem darunter angeordneten einzelnen Text aufgegeben worden. In placeit 3 kann jedes Slide aus einer Kombination von Text, Bildern und Videos bestehen.

Es ist vorgesehen, dass weitere Medientypen wie GPX-Dateien oder PDFs zum Download ebenfalls Bestandteil der Slidelist sein können. Damit sollen sowohl Objekte wie Scorekarten als auch Streckenprofile bereitgestellt werden können, damit auch diese Informationen aus einer Hand verfügbar sind.
Ebenfalls kann diese Funktionalität dazu genutzt werden, um Planungsunterlagen wie Spreadsheets oder auch aktive Inhalte für Planer und Organisatoren bereitzustellen.

Feature eines Geoitems

Detailansichten und abhängige Geoitems

Das Kategoriensystem und seine Nutzung

Initiale Anzeige und Priorität

Bilder und Icons

Die Menüs

Funktionalitäten für Fortgeschrittene