Skip to content

Appendix B: layers Field

This appendix provides a detailed description of the "layers" field, one of the fields used to define each of the Formbird components below:

1 Purpose

The "layers" field is an array of layer definitions, each defining the properties of a map layer.

  • Layers are the mechanism used to display geographic datasets on a map. Each layer definition specifies a dataset and how its elements are to be displayed on a map. E.g. a Water Utility needing to display its water pipes and water hydrants on a map would use a "layers" field with 2 layer definitions:
    • One specifying the water pipe dataset and how its elements are to be displayed on a map.
    • The other specifying the water hydrant dataset and how its elements are to be displayed on a map.
  • Each map layer definition is a set of name/value pair fields, some required, some optional.

2 Definition

The tables below lists and describes the name/value pair fields used to define the properties of a map layer.

Note:

  1. Default values for fields described in the tables below are shown in bold text.
  2. A vector feature is a point, line or polygon drawn on a map layer to represent the location of features such as water pipes, water hydrants, etc.

2.1 Required Customizable Fields

Field Valid Values Description
filter Elastic search query A query to return datasets of items (e.g. pipes, hydrants) for display in the layer.

Example:
"filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'d62a4970-d88e-11e6-92c9-934eb61df86d'}}],'must':[{'term':{'asset_category':'HYDRANT'}}]}}}"
geoJsonField A geoJson field name The document field that contains its spatial geometry i.e. its type (point, line, polygon, etc) and its coordinates.
The spatial geometry is used to render an item on a map.

Example:
"geoJsonField": "locationGeo"

2.2 Optional Customizable Fields

Field Valid Values Description
color A valid color The line colour of lines and polygons returned by a layer filter.

Example:
"color": "red"
blue Default value.
fill A valid colour The fill colour of polygons returned by a layer filter.

Example:
`"fill": "lightgreen"``
Defaults to no fill.
fillOpacity Decimal from 0 to 1 The fill opacity of polygons returned by a layer filter.

Example:
"fillOpacity": 0.5
1 Default value.
imageAnchor [x,y] The position of the top-left corner of the image used to indicate point items (e.g. Hydrants) returned by a layer filter.
Written as an array [x,y], where x and y can be zero or a positive or negative decimal number.
The x and y values indicate the position (in image widths and image heights) of the top-left corner of the image from the item's location.
[0.5,1.0] positions the top-left corner of the image (0.5 x image width) to the right and (1.0 x image height) upwards from the item's location.

Example:
"imageAnchor": [
    0.5,
    1.0
]
Defaults to:

"imageAnchor": [
    0.5,
    1.0
]
imageFileNo An image file number The image to use to indicate point items (e.g. Hydrants) returned by a layer filter query.

Example:
"imageFileNo": "62435f30-20fc-11e8-8329-0db8fb5fedc2"
Defaults to the existing image.
labelColor Valid colour value The fill colour of vector feature label text.
Colours are specified using predefined color names, HEX or RGB values

Examples:
"labelColor" : "red"
"labelColor" : "rgb(255, 0, 0)"
"labelColor" : "#ff0000"
Defaults to the layer colour i.e. the "colour" field value.
labelDisplayZoom Integer The zoom level above which vector feature labels should be displayed.

Example:
"labelDisplayZoom": 12
9 Default value.
labelFont The font of vector feature label text.

Example:
"labelFont": "Courier"
Arial Default value.
labelFontSize The font size in pixels (px) or points (pt) of vector feature label text.

Examples:
"labelFontSize": "16px"
"labelFontSize": "16pt"
12px Default value.
labelFontWeight The font weight of vector feature label text.
bold Bold the vector feature label text.

Example:
"labelFontWeight": "bold"
normal Default value.
Do not bold the vector feature label text.
labelMaxAngle Angle in degrees When "placement" is set to "line", the maximum angle between adjacent characters of vector feature label text.

Example:
"labelMaxAngle": 45
90 Default value.
labelOffsetX Integer Horizontal offset in pixels of vector feature labels. A positive value will shift the label text right, a negative value will shift the label text left.

Example:
"labelOffsetX": 10
0 Default value.
labelOffsetY Integer Vertical offset in pixels of vector feature labels. Positive values shift label text down, negative values shift label text up.

Example:
"labelOffsetY": 10
0 Default value.
labelOutlineColor Valid colour value The outline colour of vector feature label text.
Colours are specified using predefined color names, or RGB, HEX values.

Examples:
"labelOutlineColor": "black"
"labelOutlineColor": "rgb(255, 0, 0)"
"labelOutlineColor": "#000000"
white Default value.
labelOutlineWidth Integer The outline width in pixels of vector feature label text.

Example:
"labelOutlineWidth": 3
5 Default value.
labelOverflow false For polygon labels or when "placement" is set to "line", do not allow the label text to exceed the width of the polygon or the length of the line that it follows.

Example:
"labelOverflow": false
true Default value.
For polygon labels or when "placement" is set to "line", allow the label text to exceed the width of the polygon or the length of the line that it follows.
labelPadding Array of 4 integers An array specifying the padding in pixels around the vector feature label text for decluttering and background purposes.
The order of values in the array is [top, right, bottom, left].

Example:
"labelPadding": [5,2,5,2]
"" Defaults to null.
labelPlacement The placement of vector feature label text. relative to the vector feature.
Values are either 'line' or 'point'. 'line' can only be used with a line or polygon and tries to set the label to follow the line
line The placement of label text will try to follow the line of a vector feature.
Note: "line" can only be used with vector features whose geometry is a line or polygon.

Example:
"labelPlacement": "line"
point Default value.
The placement of label text will be relevant to a point on the vector feature.

Example:
"labelPlacement": "point"
labelRotation Angle in degrees The number of degrees to rotate clockwise vector feature labels.

"labelRotation": 90
0 Default value.
LabelRotationWithView true Rotate the vector feature label text with the view.

Example:
"LabelRotationWithView": true
false Default value.
Do not rotate the vector feature label text with the view.
labelText String The vector feature label text.
The string value can incorporate handlebars expansion values just like the tooltips field.

Example
"labelText": "{{{systemHeader.summaryName}}} Pipe"
"" Default value is null. The vector feature displays without a label.
labelTextAlign The alignment of vector feature label text.
The alignment is relative to a geometery point of the vector feature, meaning the label remains anchored to the vector feature on zoom and pan.
left Left align vector feature label text.

Example
"labelTextAlign" : "left"
right Right align vector feature label text.

Example
"labelTextAlign" : "right"
center Center vector feature label text.

Example
"labelTextAlign" : "center"
start Same as left if the vector feature is left to right and right if the vector feature is right to left.

Example
"labelTextAlign" : "start"
end Same as right if the vector feature is left to right and left if the vector feature is right to left.

Example
"labelTextAlign" : "end"
"" Default value is null.
labelTextBaseline The text baseline is is the imaginary line upon which a line of alphabetic text normally rests .
This field sets the vertical placement of text relative to this normal text baseline.

For each field value, the image below shows how text would be placed relative to the normal text baseline (shown in red).

labelTextBaseline-field-values
bottom Example
"labelTextBaseline" : "bottom"
top Example
"labelTextBaseline" : "top"
middle Example
"labelTextBaseline" : "middle"
alphabetic The text baseline is the normal alphabetic baseline

Example
"labelTextBaseline" : "alphabetic"
hanging Example
"labelTextBaseline" : "hanging"
ideographic Example
"labelTextBaseline" : "ideographic"
"" Default value is null.
layerDisplayOnly true Sets the layer to display only, preventing the selection of items returned by a layer filter.

Example:
"layerDisplayOnly": true
false Default value. Allows the selection of items returned by a layer filter.
lineCap The line end style of lines and polygons returned by a layer filter.
square Lines ends are square.

Example:
"lineCap": "square"
round Default value. Lines ends are rounded.
lineDash [x,y] The line dash pattern of lines and polygons returned by a layer filter.
Defined by an array [x,y] of 2 numbers where x is the dash length, y is the gap length.

Example:
"lineDash": [
    10,
    5
]
Defaults to no dash pattern i.e. a solid line.
lineWidth Decimal number The line width of lines and polygons returned by a layer filter.

Example:
"lineWidth": 2
4 Default value.
tooltips handlebar syntax Defines the tooltip text to display on mouseover of an item returned by a layer filter.

Example:
"tooltips": "PIPE <b>{{{systemHeader.summaryName}}}</b> created on {{{systemHeader.createdDate}}}"

Example:
This example includes a hyperlink in the tooltip, in this case to open a document.
"tooltips": "tooltips": "<a href='/#/form/{{{documentId}}}' target='_blank'>{{{systemHeader.summaryName}}}</a>"
Defaults to no tooltip text is displayed on mouseover of an item returned by a layer filter.

3 Example

A layers field with four layers.

    "layers": [
        {
            "color": "red",
            "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'d62a4970-d88e-11e6-92c9-934eb61df86d'}}],'must':[{'term':{'asset_category':'HYDRANT'}}]      }}}",
            "geoJsonField": "locationGeo",
            "imageAnchor": [
                0.5,
                1
            ],
            "imageFileNo": "62435f30-20fc-11e8-8329-0db8fb5fedc2",
            "labelColor": "darkred",
            "labelDisplayZoom": 13,
            "labelRotation": 90,
            "labelText": "{{{systemHeader.summaryName}}}",
            "labelTextAlign": "center",
            "tooltips": "HYDRANT {{{systemHeader.summaryName}}} created on {{{systemHeader.createdDate}}}"
        },
        {
            "color": "green",
            "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'d62a4970-d88e-11e6-92c9-934eb61df86d'}}],'must':[{'term':{'asset_category':'VALVE'}}]      }}}",
            "geoJsonField": "locationGeo",
            "imageFileNo": "355f8520-20fc-11e8-8329-0db8fb5fedc2",
            "tooltips": "VALVE {{{systemHeader.summaryName}}} created on {{{systemHeader.createdDate}}}"
        },
        {
            "color": "blue",
            "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'36811ce0-d885-11e6-92c9-934eb61df86d'}}]}}}",
            "geoJsonField": "locationGeo",
            "labelDisplayZoom": 13,
            "labelPlacement": "line",
            "labelText": "{{{pipe_matrl}}} size {{{pipe_dia}}} mm",
            "lineCap": "round",
            "lineDash": [
                10,
                20
            ],
            "lineWidth": 4,
            "tooltips": "PIPE {{{systemHeader.summaryName}}} created on {{{systemHeader.createdDate}}}"
        },
        {
            "color": "darkgreen",
            "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'b186a6b0-e439-11e7-8f5f-61ab7876b6fa'}}]}}}",
            "geoJsonField": "gblBoundaryTestDocument",
            "fill": "lightgreen",
            "fillOpacity": 0.5,
            "labelDisplayZoom": 13,
            "labelPlacement": "line",
            "labelText": "{{{systemHeader.summaryName}}}",
            "layerDisplayOnly": true,
            "lineDash": [
                10,
                5
            ],
            "lineWidth": 2
        }
    ]