NagVis-Maps

# Statische und dynamische Maps

Die verschiedenen Ansichten in NagVis heißen "maps". Der klassische und gebräuchlichste Typ der NagVis-Maps sind die statischen Maps. Das bedeutet, dass man mit Hilfe des Web-basierten Konfigurations-Editors oder eines Text-Editors eine Map-Konfiguration erstellt.

Ab NagVis 1.7 gibt es eine neue Erweiterung der Map-Konfiguration. Sie basiert weiterhin auf dem statischen Map-Konfigurations-Ansatz, aber nun ist es möglich, diese statischen Konfigurationsteile mit dynamischen und programmierbaren Mechanismen zu erweitern.

Die neue Möglichkeit wurde "map sources" benannt. Jede Map kann eine oder mehreren Map-Sources nutzen. Jede dieser Sources kann die gesamte Map-Konfiguration löschen, ersetzen oder verändern.

Ein Map-Source besteht aus verschiedenen PHP-Funktionen mit einem standardisierten Satz von Parametern. Die Funktionen sind komplett frei in dem, was sie tun. Eine Source kann z.B. CSV-Datei mit Objekten und Koordinaten lesen, sich mit Datenbanken verbinden, um Informationen zu holen, oder Daten von externen Diensten lesen. Der Entwickler entscheidet.

## Die Map-Sources-API

Textdateien mit PHP-Code müssen im Verzeichnis `share/server/core/sources` relativ zum NagVis-Basis-Verzeichnis stehen. In OMD werden die Site-spezifischen Dateien im Verzeichnis `local/share/nagvis/htdocs/server/core/sources` relativ zum Site-Basisverzeichnis abgelegt.

Es gibt keine 1:1-Relation zwischen den Dateien und den Sources selbst. Eine Datei kann eine, mehrere oder gar keine Source enthalten (z.B. um Funktionen zu definieren, die von mehreren Sources benutzt werden).

Eine Map-Source besteht aus zwei PHP-Funktionen, die die folgenden Spezifikationen erfüllen müssen:

Funktionsnamenmuster | Parameter
--- | ---
    process_<source-name>
Dies ist die tatsäliche Verarbeitungsfunktion. Sie kann die aktive Map-Konfiguration ersetzen. Der Return-Code der Funktion wird im Moment nicht genutzt. | `$MAPCFG` - das GlobalMapCfg-PHP-Objekt
`$map_name` - der Name der Map als Zeichenkette
`&$map_config` - Referenz des Map-Konfigurations-Arrays. Dieses Array muss modifiziert werden, um die Map-Konfiguration zu ändern.
    changed_<source-name>
Diese Funktion wird genutzt, um der Verarbeitung der Map-Konfigurationen mitzuteilen, ob sie erneut geladen werden muss oder nicht. Die Funktion muss "true" zurückliefern, damit NagVis die Konfiguration erneut verarbeitet. Das bedeutet auch, dass die process_* für alle konfigurierten Sources ausgeführt wird. | `$MAPCFG` - das GlobalMapCfg-PHP-Objekt
`$compare_time` - der Unix-Zeitstempel der aktuell zwischengespeicherten Map-Konfiguration.

Während eine Map-Konfiguration geladen wird, prüft NagVis, ob diese bereits analysiert und zwischengespeichert wurde. Ist das der Fall und der Cache ist aktuell, dann kann NagVis diese Daten viel schneller verarbeiten als wenn die Daten erst analysiert und geprüft werden müssten.

Im Allgemeinen vergleicht NagVis die Zeitstempel der verwendeten Konfigurationsdateien (Haupt- und Map-Konfigurationsdateien) mit dem Map-Konfigurations-Cache, um diese Entscheidung zu treffen.

Wenn Map-Sources verwendet werden, muss jede Source dem Map-Konfigurationsverarbeitungs-Code mitteilen, ob die Map-Konfiguration erneut geladen werden muss oder der Map-Konfigurations-Cache benutzt werden kann. Dies erfolgt durch die changed_*-Funktion jeder Source. Wenn diese Funktion "true" zurückliefert, wird NagVis die Map-Konfiguration erneut laden.

Die Map-Konfiguration zu laden bedeutet, dass NagVis die Map-Konfigurationsdatei analysiert, um das Array der Map-Objekte zu füllen. Dann werden diese Daten geprüft, um fehlerhafte Konfigurationen zu verhindern. Danach werden alle konfigurierten Map-Sources verarbeitet, um diesen die Möglichkeit zu geben, die Map-Konfiguration zu verändern.

Jede Map-Source kann Anzeigeparameter und Konfigurationsvariablen definieren, die in den Maps verfügbar sind, die diese Sourcen verwenden. Dies ist eine Beispieldefinition der Geomap-Map-Source:

    // options to be modifiable by the user(url)
    global $viewParams;
    $viewParams = array(
        'geomap' => array(
            'zoom',
            'geomap_type',
            'source_file',
        )
    );

    // Config variables to be registered for this source
    global $configVars;
    $configVars = array(
        'geomap_type' => array(
            'must'       => false,
            'default'    => 'osmarender',
            'match'      => '/^(osmarender|mapnik|cycle)$/i',
            'field_type' => 'dropdown',
            'list'       => 'list_geomap_types',
        ),
        'source_file' => array(
            'must'       => false,
            'default'    => '',
            'match'      => MATCH_STRING_EMPTY,
            'field_type' => 'dropdown',
            'list'       => 'list_geomap_source_files',
        ),
        'zoom' => array(
            'must'       => false,
            'default'    => '',
            'match'      => MATCH_INTEGER_EMPTY,
        ),
    );

Diese Definitionen führen zu a) drei neuen Map-Konfigurationsoptionen im global-Abschnitt der Map und b) zur Verfügbarkeit der Variablen in den URLs der Maps, die diese Source verwenden.

## Allgemeine Map-Anzeigeparameter

Seit der Implementierung der Map-Sources können sogar reguläre Maps ohne konfigurierte Sources mit Hilfe einiger Standard- Anzeigeparameter verändert werden. Einige der Parameter sind nicht komplett neu, sondern sie wurden lediglich zu Anzeigeparametern. umkodiert. Hier ist die Liste der allgemeinen Anzeigeparameter:

Parameter | Beschreibung
--- | ---
backend_id | Ändert das zu verwendende Standard-Backend der aktuellen Map. Einzelheiten finden Sie in der Beschreibung der Option in der Map-Konfiguration.
iconset | Überschreibt das iconset, das im global-Abschnitt der Map konfiguriert ist. Einzelheiten finden Sie in der Beschreibung der Option Map-Konfiguration.
width | Kann benutzt werden, um die Breite der Map-Anzeige zu ändern. Wird zurzeit nicht von regulären Maps verwendet. Diese Option wird nur von einigen Map-Sources benutzt.
height | Kann benutzt werden, um die Höhe der Map-Anzeige zu ändern. Wird zurzeit nicht von regulären Maps verwendet. Diese Option wird nur von einigen Map-Sources benutzt.
header_menu | Überschreibt die header_menu-Einstellung im global-Abschnitt der Map. Einzelheiten finden Sie in der Beschreibung der Option in der Map-Konfiguration.
hover_menu | Überschreibt die hover_menu-Einstellung im global-Abschnitt der Map. Einzelheiten finden Sie in der Beschreibung der Option in der Map-Konfiguration.
context_menu | Überschreibt die context_menu-Einstellung im global-Abschnitt der Map. Einzelheiten finden Sie in der Beschreibung der Option in der Map-Konfiguration.

## Standard-Map-Sources

Im Moment sind zwei Map-Sources für NagVis verfügbar. Beschreibungen zu den geomap- und den automap-Sources finden Sie auf den jeweils Dokumentationsseiten.