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:
- Default values for fields described in the tables below are shown in bold text.
- 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:
|
[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). |
|
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
}
]
ƒ