Static and dynamic maps

The different views in NagVis are named "maps". The classic and most common type of NagVis maps are the static maps. This means one creates a map configuration using the web based configuration editor or using a text editor to create the map configuration.

In NagVis 1.7x a new extension has been made to the map configuration. It is still based on the static map configuration approach but now it is possible to extend those static configuration parts using dynamic and programmable mechanisms.

The new feature has been named "map sources". Each map can make use of one or several map sources. Each of these sources can clear, replace, or alter the whole map configuration.

A map source is built of several PHP functions which take a standardised set of parameters to do their work. The functions are completely free in what they are doing. A source can read CSV files with objects and coordinates, can connect to databases to fetch information, or read data from external services. It is up to the developer.

The map sources API

Text files containing PHP code need to be placed in the share/server/core/sources directory relative to the NagVis base directory. In OMD the site local files can be placed in local/share/nagvis/htdocs/server/core/sources relative to the site base directory.

There no 1:1 relation between the files and the sources themselves. A file can contain one source, several different sources, or even no sources (e.g. to define functions needed by several sources).

One map source consists of two PHP functions which must match the following specifications:

process_<source-name>

changed_<source-name>

When loading a map configuration NagVis checks whether or not the map configuration has already been parsed and cached. If the map is already cached and the cache is up-to-date NagVis can use the map configuration cache which can be processed much faster than parsing and validating the map configuration.

In general NagVis compares the file ages of the used config files (main configuration and map configuration files) with the map configuration cache to make the decision.

When using map sources each source must tell the map config processing code whether or not the map source thinks that the map configuration has to be reloaded or can use the map configuration cache. This is done by the changed_* function of each source. When this function returns "true" this tells NagVis to reload the map configuration.

Loading the map configuration means that NagVis parses the map configuration file to fill the array of map objects. Then this information is validated to prevent broken configurations. Then all configured map sources are processed to provide the opportunity to alter the map configuration.

Each map source can define view parameters and config variables to be available in maps which make use of these sources. This is an example definition of the 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,
    ),
);
  

These definitions lead to a) three new map configuration options for the global section of the map and b) make these three URL parameters available in the URLs of the maps using this source.

General map view parameters

Since implementation of the map sources feature even regular maps without any configured sources can be modified using some default view parameters. Some of the parameters are not completely new, they have just been recoded to be view parameters. Here is the list of general view parameters:

Default map sources

At the moment there are three map sources available in default NagVis. Descriptions about the geomap, the automap and the dynmap sources can be found on their dedicated documentation pages.