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 map layer definitions, each defining the properties of a map layer.

  • Layers are the mechanism used to display geographic datasets on a map. Each map 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 map 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.
  • The "layers" field definition provides fields for setting the properties of each map layer and is fully described below.

 

2 Definition

Each map layer is defined by a set of name/value pair fields consisting of:

  • Required customizable fields
  • Optional customizable fields

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 the 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'}}]}}}"

The query can include none, one or more Handlebars expressions. See Appendix E: Handlebars Usage in Formbird for a detailed description of how to incorporate the Handlebars templating language within a Formbird template.

Example:
"filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'36811ce0-d885-11e6-92c9-934eb61df86d'}}, {'term':{'pipe_matrl':'{{document.filterPipes}}'}}]}}}"

In this example the expression wrapped in double curly braces i.e. {{document.filterPipes}} is a handlebars expression and means look up the filterPipes field in the current document and use its value.
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
additionalQueryFields Array of field names An array of additional fields to be returned by the filter query so they can be used in handlebars etc.

Example:
"additionalQueryFields": [
    "connection_status",
     "wat_category",
     "pipe_matrl",
    "locationGeo",
]
Defaults to no additional fields are returned by the filter query.
assetSelectionsAvailable Array of valid string values An array of one or more of the following valid string values:
"primary", "secondary" and "all" where:
"primary" allows an asset from the layer to be selected as a primary asset.
"secondary" allows an asset from the layer to be selected as a secondary asset.
"all" allows an asset from the layer to be selected as a primary or a secondary asset.

Examples:
"assetSelectionsAvailable": ["primary"]
"assetSelectionsAvailable": ["Secondary"]
"assetSelectionsAvailable": ["Primary","SECONDARY"]
"assetSelectionsAvailable": ["all"]

Note:
  • The valid string values are case insensitive.
  • The array of valid string values can be listed in any order.
  • If "layerDisplayOnly" true then the assetSelectionsAvailable field is ignored.
    [all] Default value.
    color A valid color The line colour of lines and polygons returned by a layer filter.
    Colours are specified using predefined color names, HEX or RGB values.

    Examples:
    "color": "green"
    "color": "#008000"
    "color": "rgb(0,128,0)"
    blue Default value.
    fill A valid colour The fill colour of polygons returned by a layer filter.
    Colours are specified using predefined color names, HEX or RGB values

    Examples:
    "fill": "lightgreen"
    "fill": "#90EE90"
    "fill": "rgb(144,238,144)"
    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.
    fillOpacityHandlebars handlebars expression The fill opacity of polygons returned by a layer filter.
    When the template is executed, the handlebars expression is replaced with decimal number value from 0 to 1 from an input object e.g. a field in the current document.

    Example:
    "fillOpacityHandlebars": "{{document.fillOpacitySetting}}"

    In this example the expression wrapped in double curly braces is a handlebars expression. {{document.fillOpacitySetting}} means look up and use the value of the fillOpacitySetting field in the current document.
    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
    ]
    imageAnchorHandlebars Array of 2 handlebars expressions The position of the top-left corner of the image used to indicate point items (e.g. Hydrants) returned by a layer filter.
    When the template is executed, the handlebars expressions are replaced with decimal number values from input objects e.g. fields in the current document.
    These values indicate the position (in image widths and image heights) of the top-left corner of the image from the item's location.
    On execution, if the array of handlebars expressions were replaced by [0.5,1.0] then this 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:
    "imageAnchorHandlebar": [
        {{document.imageAnchorXHandlebars}},
        {{document.imageAnchorYHandlebars}}
    ]

    In this example the expressions wrapped in double curly braces are handlebars expressions. {{document.imageAnchorXHandlebars}} means look up and use the value of the imageAnchorXHandlebars field in the current document.
    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.
    Note
    Easiest method to load alternative fonts is to place a sc-static-html component before the mapping component. The example below would load a public font from Google Fonts.

    Example:
    {
         "componentName": "sc-static-html"
         "label": "load fonts for layers labels",
        "html": "<style> @import url('https://fonts.googleapis.com/css?family=Indie+Flower
    }

    The value of the labelFont field could then defined as:
    "labelFont": "ZCOOL QingKe HuangYou"
    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.
    labelMaxAngleHandlebars handlebars expression When "placement" is set to "line", the maximum angle between adjacent characters of vector feature label text.
    When the template is executed, the handlebars expression is replaced with an angle value in degrees from an input object e.g. the value of a field in the current document.

    Example:
    "labelMaxAngleHandlebars": "{{document.MaxAngleHandlebarsSetting}}"

    In this example the expression wrapped in double curly braces is a handlebars expression. {{document.MaxAngleHandlebarSetting}} means look up and use the value of the MaxAngleHandlebarsSetting field in the current document.
    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.
    labelOffsetXHandlebars handlebars expression 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.
    When the template is executed, the handlebars expression is replaced with an integer value from an input object e.g. the integer value of a field in the current document.

    Example:
    "labelOffsetXHandlebars": "{{document.labelOffsetXSetting}"

    In this example the expression wrapped in double curly braces is a handlebars expression. {{document.labelOffsetXSetting}} means look up and use the value of the labelOffsetXSetting field in the current document.
    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.
    labelOffsetYHandlebars handlebars expression Vertical offset in pixels of vector feature labels. A positive value will shift the label text down, a negative value will shift the label text up.
    When the template is executed, the handlebars expression is replaced with an integer value from an input object e.g. the integer value of a field in the current document.

    Example:
    "labelOffsetYHandlebars": "{{document.labelOffsetYSetting}}"

    In this example the expression wrapped in double curly braces is a handlebars expression. {{document.labelOffsetY}} means look up and use the value of the labelOffsetYSetting field in the current document.
    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.
    labelOutlineWidthHandlebars handlebars expression The outline width in pixels of vector feature label text.
    When the template is executed, the handlebars expression is replaced with an integer value from an input object e.g. the integer value of a field in the current document.

    Example:
    "labelOutlineWidthHandlebars": "{{document.labelOutlineWidth}}"

    In this example the expression wrapped in double curly braces is a handlebars expression. {{document.labelOutlineWidth}} means look up and use the value of the labelOutlineWidth field in the current document.
    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.
    labelOverflowHandlebars handlebars expression 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.
    When the template is executed, the handlebars expression is replaced with a true/false value from an input object e.g. the true/false value of a check box field in the current document.

    Example:
    "labelOverflowHandlebars": "{{document.labelOverflow}}"

    In this example the expression wrapped in double curly braces is a handlebars expression. {{document.labelOverflow}} means look up and use the value of the labelOverflow field in the current document.
    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.
    labelPaddingHandlebars Array of 4 handlebars expressions 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].
    When the template is executed, the handlebars expressions are replaced with integer values from input objects e.g. fields in the current document.

    Example:
    "labelPaddingHandlebars": "[ {{document.labelPaddingTop}}, {{document.labelPaddingRight}}, {{document.labelPaddingBottom}}, {{document.labelPaddingLeft}} ]"

    In this example the expressions wrapped in double curly braces are handlebars expressions. E.g. {{document.labelPaddingTop}} means look up and use the value of the labelPaddingTop field in the current document.
    "" 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.
    labelRotationHandlebars handlebars expression The number of degrees to rotate clockwise vector feature labels.
    When the template is executed, the handlebars expression is replaced with an angle value in degrees from an input object e.g. the value of a field in the current document.

    "labelRotationHandlebars": "{{document.labelRotationSetting}}"

    In this example the expression wrapped in double curly braces is a handlebars expression. {{document.labelRotationSetting}} means look up and use the value of the labelRotationSetting field in the current document.
    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.
    labelRotationWithViewHandlebars handlebars expression Rotate the vector feature label text with the view.
    When the template is executed, the handlebars expression is replaced with a true/false value from an input object e.g. the true/false value of a check box field in the current document.

    Example:
    "labelRotationWithViewHandlebars": "{{document.labelRotationWithViewSetting}}

    In this example the expression wrapped in double curly braces is a handlebars expression. {{document.labelRotationWithViewSetting}} means look up and use the value of the labelRotationWithViewSetting field in the current document.
    false Default value.
    Do not rotate the vector feature label text with the view.
    labelText String The label text for a vector feature (i.e. points, lines, polygons) returned by the filter field.
    The string value can include none, one or more Handlebars expressions. See Appendix E: Handlebars Usage in Formbird for a detailed description of how to incorporate the Handlebars templating language within a Formbird template.

    Example:
    "labelText": "{{systemHeader.summaryName}} Pipe"

    In this example the expression wrapped in double curly braces i.e. {{systemHeader.summaryName}} is a handlebars expression and means look up the systemHeader.summaryName field in the current document and use its value.

    Example:
    "labelText": "{{result.pipe_matrl}} size {{result.pipe_dia}} mm"

    In this example the expressions wrapped in double curly braces are handlebars expressions. E.g. {{result.pipe_matrl}} means look up and use the values of the pipe_matrl field in the currently selected result returned by a Formbird filter query.
    "" 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 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 for lines and polygons returned by a layer filter.
    Defined by an ordered array [x,y] of 2 numbers where x is the line dash length, y is the line dash gap length.

    Example:
    "lineDash": [
        10,
        5
    ]
    Defaults to no dash pattern i.e. a solid line.
    lineDashHandlebars Array of 2 handlebars expressions The line dash pattern for lines and polygons returned by a layer filter.
    Defined by an ordered array or 2 handlebars expressions whose values equate to [line dash length, line dash gap length]
    When the template is executed, the handlebars expressions are replaced with integer values from input objects e.g. fields in the current document.

    Example:
    "lineDashHandlebars": "[
        {{document.lineDashXSetting}},
        {{document.lineDashYSetting}}
    ]"

    In this example the expressions in curly braces are handlebars expressions. E.g. {{document.lineDashXSetting}} means look up and use the value of the lineDashXSetting field in the current document.
    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.
    lineWidthHandlebars handlebars expression The line width of lines and polygons returned by a layer filter.
    When the template is executed, the handlebars expression is replaced with a decimal number value from an input object e.g. the decimal number value of a field in the current document.
    Example:
    "lineWidthHandlebars": "{{document.lineWidthSetting}}"

    In this example the expression wrapped in double curly braces is a handlebars expression. {{document.lineWidthSetting}} means look up and use the decimal number value of the lineWidthSetting field in the current document.
    4 Default value.
    tooltips String Defines the tooltip text to display on mouseover of an item returned by a layer's filter field.
    The string value can include one or more Handlebars expressions. See Appendix E: Handlebars Usage in Formbird for a detailed description of how to incorporate the Handlebars templating language within a Formbird template.

    Example:
    "tooltips": "PIPE {{result.pipe_matrl}} <a href='/form/{{result.documentId}}' target='_blank'>{{result.systemHeader.summaryName}}</a> created on {{result.systemHeader.createdDate}}"

    Example:
    "tooltips": "Displaying Pipes of type {{document.filterPipes}} Pipe #{{resultsIndex}} of {{resultsCount}} size {{result.pipe_dia}} mm <a href='/form/{{result.documentId}}' target='_blank'>{{result.systemHeader.summaryName}}</a> Current User {{account.systemHeader.summaryName}} viewing {{tplItem.name}}"
    Defaults to no tooltip text is displayed on mouseover of an item returned by a layer filter.
    updateWatchFields Array of field names An array of field names in the document that are watched for changes in their values. Changes to the value of one of more of the array fields will trigger a redraw of the map layer.
    The updateWatchFields is generally used when one or more of the fields being watched is also used to define the value of the layer's filter field and/or tooltips field.

    Example:
    "updateWatchFields": [
            "document.filterPipes",
            "document.labelPlacement",
            "document.backgroundColor"
    ]

    Note: The syntax for specifying a field name as a value in the updateWatchFields array is the field name prefixed with document. e.g. "document.filterPipes".
    Defaults to no fields in the document will be watched for change in value. Hence a change the value of a field will not trigger a redraw of the map layer.

     

    3 Examples

    Example 1

    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'}}, {'term':{'pipe_matrl':'{{document.filterPipes}}'}}]}}},
            "geoJsonField": "locationGeo",
            "labelDisplayZoom": 13,
            "labelPlacement": "line",
            "labelText": "{{result.pipe_matrl}} size {{result.pipe_dia}} mm",
            "lineCap": "round",
            "lineDash": [
                20,
                5
            ],
            "lineWidth": 2,
            "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
        }
    ]

    ƒ