Skip to content

sc-address-map

This document is a user guide for the sc-address-map component version 5.30, released May 15, 2019.

go-to-typical-definition

sc-address-map-field-Example-1-Image-1 is

1 Purpose

sc-address-map places a map on a form. The map uses icons/markers to show the geospatial location of documents that define points, lines, polygons or images and are returned by a filter query and have a specified address field name. Clicking an icon/marker opens the associated document. Tooltip text can be configured to display on mouseover of an icon/marker. Map buttons provide the ability to zoom in, zoom out, select single or multiple assets and toggle full screen.

The sc-address-map definition provides fields for setting the properties of an address map field and is fully described below.

2 Definition

sc-address-map is defined by a set of name/value pair fields consisting of:

  • Required system fields
  • Required customizable fields
  • Optional customizable fields

Note:

  1. Default values for fields described in the tables below are shown in bold text.
  2. Most fields in the tables and/or examples below use a single name/value pair to define a property of the sc-address-map component e.g. "mandatory": true.

    Whereas the fields "layers", "mapParameters" and "mapViews" require a set of name/value pair fields to define a property of the sc-address-map component. The tables below provide a summary description of these fields and a link to an Appendix that has the detailed description. Links to these appendices are also listed below.

2.1 Required System Fields

Field Valid Values Description
componentName sc-address-map The component name.

Example:
"componentName": "sc-address-map"

2.2 Required Customizable Fields

Field Valid Values Description
name Any value written in camel case. Defines the name of the address map field in the document and database.

Example:
"name": "testScAddressMap"

2.3 Optional Customizable Fields

Field Valid Values Description
addressField An address field name The addressField works in conjunction with the filter field.
The GeoJSON field name in documents returned by the filter field query must be the addressField value.
If the addressField and filter fields are not both specified, then no documents will display on the map.

Example:
"addressField": "locationGeo"
color A valid color The line colour of lines and polygons returned by the "filter" field query.
Colours are specified using predefined color names, HEX or RGB values

Example:
"color": "green"
"color": "#008000"
"color": "rgb(0,128,0)"
purple Default value.
disableMouseWheel true Disable the ability to zoom the map using the mouse wheel.

Example:
"disableMouseWheel": true"
false Default value. Enable the ability to zoom the map using the mouse wheel.
disableSave true Changing the sc-address-map field value (i.e. selecting an item from the map) does not trigger the Save icon to flash.
Exiting the form without saving changes to the sc-address-map field value does not trigger a warning message to display.
In the Angular version of the sc-address-map component, clicking the Save icon will not save the sc-address-map field value to the document.
In the AngularJS version of the sc-address-map component, clicking the Save icon will save the sc-address-map field value to the document.

Example:
"disableSave": true
false Default value.
Changing the sc-address-map field value (i.e. selecting an item from the map) does trigger the Save icon to flash..
Exiting the form without saving changes to the sc-address-map field value does trigger a warning message to display.
In both the Angular and AngularJS versions of the sc-address-map component, clicking the Save icon will save the sc-address-map field value to the document.
enabled false Disables the "Asset Selection" buttons.
A Stop icon appears on mouseover of the "Asset Selection" buttons.
The "Zoom", "Full Screen" and "Map View" buttons remain enabled.

Example:
"enabled": false
true Default value. All buttons are enabled.
EPSG Valid EPSG SRID EPSG is a spatial coordinate system used to locate geographical entities on a map, a map being a 2D projection of the 3D earth's surface or a region of the earth's 3D surface. There are many 2D projections, each using different properties to represent distances, angles or areas. Certain projections are better suited for different regions in the world.
An EPSG SRID (Spatial Reference System Identifier) value identifies a specific 2D projection coordinate system together with the region of the earth it covers. E.g. EPSG:3111 is the projection coordinate system used for rendering map of the state of Victoria (between 140.9500, -39.1500 and 149.9800, -34.0000).

Example:
"EPSG": "EPSG:3111"
EPSG:3857 Defaults to the Web Mercator projection (EPSG:3857) which is used to render a map of the world (between 85.06°S and 85.06°N) for online mapping applications such as Google Maps, OpenStreetMaps, OpenLayers, Bing and ESRI.
filter Elastic search query The filter works in conjunction with the addressField field.
A query to select the documents for display as icons/markers (e.g. points, lines. Polygons, etc.) on a map.
If the addressField and filter fields are not both specified, then no documents will display on the map.

Example:
To locate documents containing the field named "address":
"filter": "{'query':{'exists':{'field':'address'}}}"

Example:
To locate documents created using a particular templateId:
"filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'02e92c00-d8b3-11e6-92c9-934eb61df86d'}}]}}}"

Example:*
To locate documents matching multiple criteria:
"filter": "{'query':{'bool':{'filter':[{'term':{ 'appTags': 'asset'}},{'term':{ 'appTags': 'sewerGravityPipe'}},{'term':{'systemHeader.systemType':'document'}}], 'should':[{'term':{'operational_state': 'ACTIVE'}},{'term':{'operational_state': 'PROPOSED'}},{'term':{'operational_state': 'UNKNOWN'}}]}}}"

Note:
The filter can also be set/changed using the "setFilter" Ruleset function as described in the setFilter Ruleset Function Guide.
fullWidth true The sc-address-map field displays full width on the form.
Full width is recommended for the address map field.

Example:
"fullWidth": true
false Default value. The sc-address-map field does not display full width on the form.
heightNum numeric Defines the height of the address map field as a multiple of a standard height.

Example:
"heightNum": 2
1 Default value. The height of the address map field defaults to 1 standard height.
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.
initialMapView map Position the map at the point and zoom level defined by the three mapParameters fields defaultLon, defaultLat and defaultZoom.

Example:
"initialMapView": "map"
all Set the map area to the area covered by the assets returned by the filter field query and each layer's filter field query.
This value is dependent on the existence of both a filter field query and a layers filter field query.

Example:
"initialMapView": "all"
layers Set the map area to the area covered by the assets returned by each layer's filter query.
This value is dependent on the existence of a layer's filter field query.

Example:
"initialMapView": "layers"
filter Default value. Set the map area to the area covered by the assets returned by the filter field query.
This value is dependent on the existence of a "filter" field query.

Example:
"initialMapView": "filter"
initialZoomChange numeric The number of initial zoom in/out steps to perform after determining the initial map view. Negative value for zoom out, positive value for zoom in.
Ignored if "initialMapView": "map".

Example:
"initialZoomChange": -2
0 Default value. No initial zoom in/out is performed.
label Any value Defines the name of the address map field on the form i.e. the field label.

Example:
"label": "Test sc-address-map"
Defaults to no label is displayed.
labelColor Valid colour value The fill colour of the label text for a vector feature (i.e. points, lines, polygons) returned by the filter field.
Colours are specified using predefined color names, or RGB, HEX values

Examples
"labelColor" : "red"
"labelColor" : "rgb(255, 0, 0)"
"labelColor" : "#ff0000"
black Default value.
labelText String The label text for a vector feature (i.e. points, lines, polygons) returned by the 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
"labelText": "{{systemHeader.summaryName}}"
"" Default value is null. The vector feature displays without a label.
layers Array of map layer definitions An array of map layer definitions, each defining the properties of a map layer.
See Appendix B: layers Field for a detailed description of the "layers" field.
mandatory true Works in conjunction with the "mandatoryValuesArray" field.
The selected asset field displays as mandatory (i.e. label in red text with an asterisk).
Saving without a value in a mandatory field, a message prompts the user to enter a value for the field.

Example:
"mandatory": true
false Default value. The field displays as optional (i.e. label in black text).
mandatoryValuesArray Array of mandatory field definitions Works in conjunction with "mandatory": true .
An array of one or more mandatory field definitions, each definition specifying a field and the message to display if that field has no value.

See Section2.4 mandatoryValuesArray Field for detailed description of a mandatory field definition.
mapParameters Set of name/value fields A set of name/value pair fields that define the properties of the map.
See Appendix C: mapParameters Field for detailed description of the mapParameters field.
selection Set of name/value fields A set of name/value fields defining the display properties of items selected on the map.
See Section 2.5 selection Field for detailed description of the selection field.
selectionMode Defines the number of allowable selections i.e. single selection or multiple selections.

Clicking on an unselected item will select it.
Clicking on a selected item will deselect it.
multiple Allows multiple items to be selected.
In this mode the selection mode buttons are hidden.

Example:
"selectionMode": "multiple"
user Allows a user to switch between single selection mode and multiple selection mode.
In this mode the selection mode buttons are visible.

Example:
"selectionMode": "user"
single Default value.
Allow only one item to be selected.
In this mode the map buttons are hidden.

Example:
"selectionMode": "single"
tooltips String Defines the tooltip text to display on mouseover of an item returned by the filter field query.
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": "<b>MAIN {{systemHeader.summaryName}}</b>\nResponsible: {{resp_auth}}\nLinage: {{lineage_date}}\n{{systemHeader.summaryName}} created on {{systemHeader.createdDate}}"
Defaults to no tooltip text is displayed on mouseover of an item returned by the filter field query.
visible false The sc-address-map field is not visible on the form.

Example:
"visible": false
true Default value. The address map field is visible on the form.

2.4 mandatoryValuesArray Field

The mandatoryValuesArray field in Section 2.3 Optional Customizable Fields is an array of mandatory field definitions, one definition per mandatory field.

The table below lists and describes the fields used to define a field as mandatory.

2.4.1 Optional Customizable Fields

Field Valid Values Description
name Text The message to display if on save, the mandatory field has no value.

Example:
"name": "Please select at least one item from the map"
jsonPathQuery json path query Identifies the field to be defined as mandatory.

Example:
"jsonPathQuery": "$..[?(@.documentId)]]"

2.4.2 Example

"mandatoryValuesArray": [
    {
        "name": "Please select at least one item from the map",
        "jsonPathQuery": "$..[?(@.documentId)]"
    }
]

2.5 selection Field

The selection field in Section 2.3 Optional Customizable Fields is a set of name/value fields defining the display properties of items selected from the map.

The table below lists and describes the name/value pair fields used to define the properties the "selection" field.

2.5.1 Optional Customizable Fields

Field Valid Values Description
selectionColor A valid color The colour of selected lines and polygons.
Colours are specified using predefined color names, HEX or RGB values

Example:
"selectionColor": "blue"
"selectionColor": "#0000FF"
"selectionColor": "rgb(0,0,255)"
green Default value.
selectionFill A valid color The fill colour of selected polygons.
Colours are specified using predefined color names, HEX or RGB values

Example:
"selectionFill": "blue"
"selectionFill": "#0000FF"
"selectionFill": "rgb(0,0,255)"
Defaults to no fill.
selectionFillOpacity Decimal from 0 to 1 The fill opacity of selected polygons.

Example:
selectionFillOpacity": 0.5
1 Default value.
selectionImageAnchor [x,y] The position of the top-left corner of the image used to indicate a selected point item.
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 relative to the selected 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 selected item's location.

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

"selectionImageAnchor": [
    0.5,
    1.0
]
selectionImageFileNo Image File Number The image used to indicate a selected point item.

Example:
"selectionImageFileNo": "63d53643-65da-4db5-82f5-2af257845516"
Defaults to the existing image.
selectionLineCap The end style of selected lines and polygons.
square Lines ends are square.

Example: "selectionLineCap": "square"
round Default value.
selectionLineDash [x,y] The dash pattern for selected lines and polygons.
Defined by an array [x,y] of 2 numbers where x is the dash length, y is the gap length.

Example:
"selectionLineDash": [
    10,
    5
]
Defaults to no dash pattern i.e. a solid line.
selectionLineWidth Decimal number The line width of selected lines and polygons.

Example:
"selectionLineWidth": 2
4 Default value.

2.5.2 Example

"selection": {
    "selectionColor": "red",
    "selectionFill": "blue",
    "selectionLineDash": [
        10,
        5
    ]
}

3 Typical Definition

Below is a typical sc-address-map definition, defined with its required fields plus any optional field whose value is typically other than its default value.

 

{
    "componentName": "sc-address-map",
    "addressField": "locationGeo",
    "EPSG": "EPSG:3111",
    "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'02e92c00-d8b3-11e6-92c9-934eb61df86d'}}]}}}",
    "fullWidth": true,
    "heightNum": 2,
    "label": "Test sc-address-map",
    "layers": [
        {
            "filter": "{'query':{'bool':{'filter':[{'term':{ 'appTags': 'asset'}},{'term':{ 'appTags': 'sewerGravityPipe'}},{'term':{'systemHeader.systemType':'document'}}], 'should':[{'term':{'operational_state': 'ACTIVE'}},{'term':{'operational_state': 'PROPOSED'}},{'term':{'operational_state': 'UNKNOWN'}}]}}}",
            "color": "brown",
            "geoJsonField": "locationGeo",
            "lineWidth": 2,
            "lineCap": "round",
            "tooltips": "SEWER PIPE {{systemHeader.summaryName}}\nResponsible: {{resp_auth}}\nLinage: {{lineage_date}}\n{{systemHeader.summaryName}} created on {{systemHeader.createdDate}}"
        },
        {
            "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'b186a6b0-e439-11e7-8f5f-61ab7876b6fa'}}]}}}",
            "color": "green",
            "geoJsonField": "scBoundaryTestDocument",
            "fillOpacity": 0.2,
            "fill": "green",
            "tooltips": "Polygons : {{systemHeader.summaryName}}"
        }
    ],
    "mapParameters": {
        "defaultLon": 144.89993237404,
        "defaultLat": -37.8034619371937,
        "crossOrigin": null,
        "mapViews": [
                    {
                    "url": "https://base.maps.vic.gov.au/service",
                    "params": {
                        "LAYERS": "CARTO_WM",
                        "VERSION": "1.1.1",
                        "FORMAT": "image/png"
                    },
                    "serverType": "geoserver",
                    "tileSize": [
                        512,
                        512
                    ],
                    "extent": [
                        1786000,
                        1997264.499195665,
                        3953471.00160867,
                        3081000
                    ],
                    "resolutions": [
                        2116.670900008467,
                        1058.3354500042335,
                        529.1677250021168,
                        264.5838625010584,
                        132.2919312505292,
                        66.1459656252646,
                        26.458386250105836,
                        13.229193125052918,
                        6.614596562526459,
                        2.6458386250105836,
                        1.3229193125052918,
                        0.6614596562526459,
                        0.33072982812632296,
                        0.21166709000084669
                    ]
                }
            ],
            "minResolution": 0.21166709000084669,
            "maxResolution": 2116.670900008467,
            "defaultZoom": 15
    },
    "name": "testScAddressMap",
    "selection": {
        "selectionColor": "blue",
        "selectionLineWidth": 2,
        "selectionFill": "red",
        "selectionFillOpacity": 0.5,
        "selectionImageFileNo": "8b526c40-e1c6-44c6-9c49-61d153f07cc8",
        "selectionImageAnchor": [
            0.5,
            0
        ]
    },
    "selectionMode": "user",
    "tooltips": "MAIN {{systemHeader.summaryName}}\nResponsible: {{resp_auth}}\nLinage: {{lineage_date}}\n{{systemHeader.summaryName}} created on {{systemHeader.createdDate}}"
}

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

OPTIONAL CUSTOMIZABLE FIELDS
    "mandatory": true,
    "disableMouseWheel": true,
    "disableSave": true,
    "enabled": false,
    "visible": false,
    "initialMapView": "map",
    "initialZoomChange": -4,


LAYERS OPTIONAL CUSTOMIZABLE FIELDS
    "imageAnchor": [
        0.5,
        1.0
    ],
    "imageFileNo":"e563a940-5f01-11e8-8216-4f004fb04409",
    "layerDisplayOnly": true,
    "lineDash": [
        10,
        5
    ],


SELECTION OPTIONAL CUSTOMIZABLE FIELDS
    "selectionLineCap":"square",
    "selectionLineDash": [
        10,
        5
    ],

4 Examples

Example 1

sc-address-map defined with its required fields plus its optional fields. The required system field "componentName" is shown first followed by the other fields shown in alphabetical order. However the fields can be defined in any order.

 

        {
            "componentName": "sc-address-map",
            "addressField": "locationGeo",
            "disableMouseWheel": false,
            "disableSave": false,
            "enabled": true,
            "EPSG": "EPSG:3111",
            "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'d62a4970-d88e-11e6-92c9-934eb61df86d'}}]}}}",
            "fullWidth": true,
            "heightNum": 2,
            "initialMapView": "filter",
            "initialZoomChange": 0,
            "label": "Test sc-address-map",
            "layers": [
                {
                    "filter": "{'query':{'bool':{'filter':[{'term':{ 'appTags': 'asset'}},{'term':{ 'appTags': 'sewerGravityPipe'}},{'term':{'systemHeader.systemType':'document'}}], 'should':[{'term':{'operational_state': 'ACTIVE'}},{'term':{'operational_state': 'PROPOSED'}},{'term':{'operational_state': 'UNKNOWN'}}]}}}",
                    "color": "brown",
                    "geoJsonField": "locationGeo",
                    "lineDash": [
                        10,
                        5
                    ],
                    "lineWidth": 2,
                    "lineCap": "round",
                    "tooltips": "<b>SEWER PIPE {{systemHeader.summaryName}}</b>\nResponsible: {{resp_auth}}\nLinage: {{lineage_date}}\n{{systemHeader.summaryName}} created on {{systemHeader.createdDate}}"
                },
                {
                    "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.templateId':'b186a6b0-e439-11e7-8f5f-61ab7876b6fa'}}]}}}",
                    "color": "green",
                    "geoJsonField": "gblBoundaryTestDocument",
                    "layerDisplayOnly": false,
                    "fillOpacity": 0.2,
                    "fill": "green",
                    "tooltips": "Polygons : <a href='/#/form/{{documentId}}' target='_blank'>{{systemHeader.summaryName}}</a>"
                }
            ],
            "mandatory": false,
            "mapParameters": {
                "defaultLon": 144.89993237404,
                "defaultLat": -37.8034619371937,
                "crossOrigin": null,
                "mapViews": [
                    {
                        "url": "https://base.maps.vic.gov.au/service",
                        "params": {
                            "LAYERS": "CARTO_WM",
                            "VERSION": "1.1.1",
                            "FORMAT": "image/png"
                        },
                        "serverType": "geoserver",
                        "tileSize": [
                            512,
                            512
                        ],
                        "extent": [
                            1786000,-
            "selection": {
                "selectionColor": "blue",
                "selectionLineWidth": 2,
                "selectionLineDash": [
                        10,
                        5
                    ],
                "selectionFill": "red",
                "selectionFillOpacity": 0.5,
                "selectionImageFileNo": "8b526c40-e1c6-44c6-9c49-61d153f07cc8",
                "selectionImageAnchor": [
                    0.5,
                    0
                ]
            },
            "selectionMode": "user",
            "tooltips": "<b>MAIN {{systemHeader.summaryName}}</b>\nResponsible: {{resp_auth}}\nLinage: {{lineage_date}}\n{{systemHeader.summaryName}} created on {{systemHeader.createdDate}}",
            "visible": true
        }

Resulting field displayed on the form:

sc-address-map-field-Example-1-Image-1

Mouseover an icon will display a tooltip:

sc-address-map-field-Tooltip

In single-select mode, clicking an icon will open the related document:

sc-address-map-field-Example-1-Image-3

In multi-select mode, clicking a line icon will show it as selected (i.e. as a blue dashed line):

sc-address-map-field-Example-1-Image-4

The saved field in the document and database is an array of the selected documents

    "testScAddressMap": [
        {
            "name": "ZigZag on Buckley | Should now hit all the point assets",
            "documentId": "f43ad110-3df4-11e8-b0f8-a1862b480959"
        }
    ]