# 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 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:

Function name pattern | Parameters
--- | ---
    process_<source-name>
This is the real source processing function. It can alter the map configuration in place. The return code of the function is not used in any way at the moment. | `$MAPCFG` - The GlobalMapCfg PHP object
`$map_name` - The name of the map as string
`&$map_config` - Reference of the map config array. This array must be modified to alter the map configuration.
    changed_<source-name>
This function is used to tell the map config processing of NagVis whether or not the the map configuration has to be reloaded. It must return "true" to tell NagVis to reload the map configuration. This means also to execute the process_* function of all configured sources. | `$MAPCFG` - The GlobalMapCfg PHP object
`$compare_time` - The unix timestamp of the currently cached map configuration.

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:

Parameter | Description
--- | ---
backend_id | Changes the default backend to be used in the current map. Take a look at the map configuration option for details.
iconset | Overrides the iconset configured in global section of the map. Take a look at the map configuration option for details.
width | Can be used to alter the map configuration dimensions. Is not used by regular maps at the moment. This option is only used by some map sources.
height | Can be used to alter the map configuration dimensions. Is not used by regular maps at the moment. This option is only used by some map sources.
header_menu | Overrides the header_menu setting configured in global section of the map. Take a look at the map configuration option for details.
hover_menu | Overrides the hover_menu setting configured in global section of the map. Take a look at the map configuration option for details.
context_menu | Overrides the context_menu setting configured in global section of the map. Take a look at the map configuration option for details.

## Default map sources

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