Creating & updating layers
==========================


Default variables
"""""""""""""""""
.. http:post:: /maps_api/v2/server/viewers/(string:identifier)/layers

    All layer types share these variables:

    :<json string name:
        The name of the layer.

    :<json string type:
        See :http:get:`/maps_api/v2/server/layer_types` for a list of possible
        layer types. This should contain one of the values specified.

    :<json boolean base:
        Whether the layer should be a base layers. See the Maps API
        introduction and glossary for more details. This field is optional, by
        default it is ``false``.

    :<json boolean consultable:
        Whether the layer should be consultable (i.e. feature information
        should be exposed to the user. Note that not sources have feature
        information (e.g. the aerial layer has no feature information). This
        field is optional, by default it is ``true``.

    :<json boolean show_layer:
        A boolean value to either show (true) or not show (false) when loading the viewer. Layer will remain available in
        the viewer and can be manually turned on.

    It's good practice to define these variables in both the create and update calls.


Base Layers
"""""""""""
    Every layer type can be used as a base layer. every viewer is created with two base layers, OSM & Aerial.
    Not every layer type is suited to be a base layer. So carefully choose what layer you want to have to project your
    other layers on.

    A base layer is defined by giving the variable "base" the value true.

    **Example JSON request:**

    .. sourcecode:: http

        {
            "name": "My background layer",
            "type": "empty",
            "base": true,
            "consultable": true
        }

.. note::
    note here that we didn't use the default variable show_layers. This is the one exception to the rule. The highest listed
    background layer will always be shown. Also only one background layer can be shown at a time.

Static Layers
"""""""""""""

    Static layers are layers you can add but have no additional options. All layer types use this structure with
    additional options.
    The layer types that are considered static are:

    * empty (White, primarily used as background)
    * osm (OpenStreetMap, default added to viewer as background layer)
    * aerial (Aerial photograph, default added to viewer as background layer)
    * dkk (map displaying lot-borders in wms format)
    * dkk_vector (map displaying lot-borders in wfs format)
    * bag (Dutch base registration addresses and buildings in wms format)
    * bag_vector (Dutch base registration addresses and buildings in wfs format)
    * imro (Ruimtelijke plannen)

    These Layers can be added or updated using the following Json request:

    **Example JSON request:**

    .. sourcecode:: http

        {
            "name": "My Layer",
            "type": "dkk",
            "base": false,
            "consultable": true,
            "show_Layer": false
        }



Shared Layers
"""""""""""""
    Shared layers are layers pulled from another viewer. These layers take a "vector" layer or outline from another viewer
    and display these as a new layer in the viewer where you added them. The source layer will remain unaltered. If you
    update the source layer/outline the shared layer will also be updated.

    The layer types for a shared layer are:

    * outline (display an outline from another viewer as shape in this viewer)
    * proxy (display a vector layer from another viewer in this viewer)

    For both types, you can only link to a viewer in it's own application. For an overview of viewers,
    See :ref:`list-viewers-label`

Outline
-------

    for creating or updating an outline-layer you will need to add two additional variables:

    * outline_target_viewer (viewer id of source viewer outline)
    * outline_clickable (boolean: true; double-click will load the targeted viewer | false: nothing will happen)

    If we take the basic Json request from above and add these two variable we'll get an Json request like this:

 **Example JSON request:**

    .. sourcecode:: http

        {
            "name": "My outline Layer",
            "type": "outline",
            "base": false,
            "consultable": true,
            "show_Layer": false,
            "outline_target_viewer": "bb02c320c4fc65ba215292727e75e2c9fe267bbb4cd6bab9c3ded261e50a7217",
            "outline_clickable": false
        }

    .. note::
        * Please make sure the targeted viewer has an outline set.
        * You can only access viewers within your application.

Proxy
-----

    For creating or updating a proxy layer you will need to add one additional variable:

    * proxy_target_layer (layer id of vector layer to be shared)

    Using the base Json request we add one variable to it.

    .. sourcecode:: http

        {
            "name": "My outline Layer",
            "type": "proxy",
            "base": false,
            "consultable": true,
            "show_Layer": false,
            "proxy_target_layer": "42"
        }

    .. note::
        * Please make sure the targeted layer is a vector layer.
        * You can only access viewers within your application.

Service Layers
""""""""""""""

    Maps API also supports the use of "Web Map Service" (wms), "Web Map Tile Service" (wmts) and "Web Feature Service" (wfs).
    These can be services hosted by you or services freely available online.

Web Map Service
---------------
    To add a WMS service to the viewer you'll need to add these to variables:

    * wms_url
    * wms_layer_name

    Adding these to the base Json request will look like this:

    .. sourcecode:: http

        {
            "name": "My WMS Service",
            "type": "wms",
            "base": false,
            "consultable": true,
            "wms_url": "https://geodata.nationaalgeoregister.nl/inspire/au/wms?",
            "wms_layer_name": "au"
        }

    .. note::
        **wms_url**: copy and pasting a url from a service might result in an empty layer. This is generally caused by
        additional variables in the service url. Should you encounter this issue we advice to remove the variables but
        leave the "?" in place.

        **wms_layer_name**: A wms service can display mutliple layers. Add the name of the layer you want to have
        displayed.
        To detect the layer name, open the wms_url in your browser. Search for Layer to detect the wms_layer_name
        you want to use. Use the name as wms_layer_name in your request.
        Unable to find the layer name? Use the Planviewer Dashboard to create a wms layer. It will list all available layers after you have entered the url.

        **multiple layers**: if you want to display two or more layers from a service you can do this by creating
        multiple layers with this service and changing the wms_layer_name accordingly.

Web Map Tile Service
---------------
    To add a WMTS service to the viewer you'll need to add these to variables:

    * wmts_url
    * wmts_layer_name

    Adding these to the base Json request will look like this:

    .. sourcecode:: http

        {
            "name": "My WMTS Service",
            "type": "wmts",
            "base": false,
            "consultable": true,
            "wmts_url": "https://geodata.nationaalgeoregister.nl/tiles/service/wmts",
            "wmts_layer_name": "bodemkaart50000"
        }

    .. note::
        **wmts_url**: copy and pasting a url from a service might result in an empty layer. This is generally caused by
        additional variables in the service url. Should you encounter this issue we advice to remove the variables but
        leave the "?" in place.

        **wmts_layer_name**: A wmts service can display mutliple layers. Add the name of the layer you want to have
        displayed.
        To detect the layer name, open the wmts_url in your browser. Search forows:Title to detect the wms_layer_name
        you want to use. Use the name as wmts_layer_name in your request.
        Unable to find the layer name? Use the Planviewer Dashboard to create a wmts layer. It will list all available layers after you have entered the url.

        **multiple layers**: if you want to display two or more layers from a service you can do this by creating
        multiple layers with this service and changing the wms_layer_name accordingly.

        **featureinfo**: We do not support feature info requests for layers of this type.

Web Feature Service
-------------------

    To add a WFS service to the viewer you'll need to add these to variables:
    * wfs_url
    * wfs_layer_name

    Adding these to the base Json request will look like this:

    .. sourcecode:: http

        {
            "name": "My WFS Service",
            "type": "wms",
            "base": false,
            "consultable": true,
            "wfs_url": "https://geodata.nationaalgeoregister.nl/inspire/au/wfs?",
            "wfs_layer_name": "au"
        }

    .. note::
        **wfs_url**: copy and pasting a url from a service might result in an empty layer. This is generally caused by
        additional variables in the service url. Should you encounter this issue we advice to remove the variables but
        leave the "?" in place.

        **wfs_layer_name**: A wfs service can display mutliple layers. Add the name of the layer you want to have
        displayed.
        To detect the layer name, open the wfs_url in your browser. Search for FeatureTypeList. Use the name as
        wfs_layer_name in your request.
        Unable to find the layer name? Use the Planviewer Dashboard to create a wfs layer. It will list all available layers after you have entered the url.

        **multiple layers**: if you want to display two or more layers from a service you can do this by creating
        multiple layers with this service and changing the wfs_layer_name accordingly.


Content Layers
""""""""""""""
    Content layers are layers where you can add geometries and information to a layer. Currently this can only be done
    with the layer type: vector.

    The way you create a vector layer determines how you are going to use it. A vector layer can be used to upload a shape
    file, to draw by hand shapes in the layer or a combination of both.

.. _createLayers-Vector:
Vector upload layer
-------------------

    If you have a shape file which you want to include in you viewer you'll need to create a vector layer for this file.
    You do this by adding these variables:

    * vector_uploadable (true = will accept a shapefile upload :http:post:`/maps_api/v2/server/viewers/(string:identifier)/layers/(int:layer)/upload`)
    * vector_type (When uploading a file you'll need to define the geometry used inside the file :http:get:`/maps_api/v2/server/vector_source_types`.)
    * vector_drawable (true = will allow you to draw shapes on the layer)

    Optional variables:
    A vector layer has some other possibilities that other layer types do not.

    * show_layer (creates a legend of this layer)
    * label_layer (uses this layer to diplay labels)
    * label_field (tells us which field to use for the labels)
    * as_wms (if true it will display the layer as tiles (wms))

    .. note::
    * The use of as_wms is advised when uploading complex shape files. The layer will display much faster as a wms layer in these cases.

    A Json request for a vector layer where you can upload a shapefile to will look like this:

    .. sourcecode:: http

        {
            "name": "My vector shape",
            "type": "vector",
            "base": false,
            "consultable": true,
            "vector_uploadable": false,
            "vector_type": "polygon",
            "vector_drawable": false
            "show_layer": false,
            "label_layer": false,
            "label_field": "Field name"
            "as_wms": true
        }

    .. note::
    * you will need to upload the shapefile in a seperate call: :http:post:`/maps_api/v2/server/viewers/(string:identifier)/layers/(int:layer)/upload`

Vector drawable layer
---------------------

    When you don't have a shapefile to upload but still want to add a shape to your viewer you can do this by creating a
    drawable vector layer. As with the vector upload layer you'll need to add three variables.

    * vector_uploadable (true = will accept a shapefile upload :http:post:`/maps_api/v2/server/viewers/(string:identifier)/layers/(int:layer)/upload`)
    * vector_type (When uploading a file you'll need to define the geometry used inside the file :http:get:`/maps_api/v2/server/vector_source_types`.)
    * vector_drawable (true = will allow you to draw shapes on the layer)

    A Json request for a vector layer where you can draw a shape will look like this:

    .. sourcecode:: http

        {
            "name": "My vector shape",
            "type": "vector",
            "base": false,
            "consultable": true,
            "vector_uploadable": false,
            "vector_type": "polygon",
            "vector_drawable": false
        }

.. _createLayers-Imrogml:
IMRO GML layer
-------------------

    If you have a gml file or zip file with a gml file in it's root, which you want to include in you viewer you'll need to create a imrogml layer for this file.

    .. note::
    * The use of as_wms is advised when uploading complex shape files. The layer will display much faster as a wms layer in these cases.

    A Json request for a vector layer where you can upload a shapefile to will look like this:

    .. sourcecode:: http

        {
            "name": "My Imro Layer",
            "type": "imrogml",
            "base": false,
            "consultable": true,
            "show_layer": false,
            "label_layer": false,
            "label_field": "Field name"
        }

    .. note::
    * you will need to upload the file in a seperate call: :http:post:`/maps_api/v2/server/viewers/(string:identifier)/layers/(int:layer)/import.gml`