Skip to content

sc-address-map

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

1 Purpose

sc-address-map places a map on a form. The map uses icons (e.g. points, lines, polygons or images) to show the geospatial location of the documents returned by a filter query and also have a specified address field name. Clicking the icon opens the document. Tooltip text can be configured to display on mouseover of an icon. 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.1 Root Level Fields

This section lists and describes the root level fields of the sc-address-map definition.

2.1.1 Required System Fields

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

2.1.2 Required Customizable Fields

Field Valid Values Description
addressField An address field name Documents returned by the filter query must have this address field name.
If "addressField" and the root level "filter" fields are not both specified, then no documents will display on the map.
Example: "addressField": "locationGeo"
filter Elastic search query A query to select the documents for display as markers on a map.
If "addressField" and the root level "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':'d62a4970-d88e-11e6-92c9-934eb61df86d'}}]}}}
name Any value written in camel case. Defines the name of the address map field in the document and database.
Example: "name": "testScAddressMap"

2.1.3 Optional Customizable Fields

Field Valid Values Description
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 Selecting an item from the map does not trigger the Save icon to flash.
Exiting the form without saving the entered value does not trigger a warning message to display.
Example: "disableSave": true
false Default value. Selecting an item from the map does trigger the Save icon to flash.
Exiting the form without saving the entered value does trigger a warning message to display.
enabled false Disables the zoom, item selection and full screen map buttons.
A Stop icon appears on mouseover of the zoom and full screen map buttons. ??? BUT not item selection buttons.
??? Clicking to open a map item is not disabled.
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) in Google Maps, OpenStreetMaps, OpenLayers, etc.
fullWidth true The 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 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.
initialMapView map Position the map at the point and zoom level defined by the "mapParameters" fields: defaultLon, defaultLa and zoom fields.
Example: "initialMapView": "map"
all Set the map area to the area covered by the assets returned by the "layers" and "layers" queries.
Example: "initialMapView": "all"
layers Set the map area to the area covered by the assets returned by the "layers" query.
Example: "initialMapView": "layers"
filter Default value. Set the map area to the area covered by the assets returned by the "filter" 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": -4
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.
layers Array of map layer definitions An array of map layer definitions, each defining the properties of a map layer. Each map layer definition is a set of name/value pair fields, some being required, some being optional.
Section 2.4 lists and describes the fields for defining the properties of a map layer.
mapParameters Set of name/value fields A set of name/value fields defining the properties of the map.
Section 2.2 lists and describes the name/value fields for defining the properties of the map.
selection Set of name/value fields A set of name/value fields defining the display properties of items selected on the map.
Section 2.5 lists and describes the name/value fields for defining the display properties of items selected on the map.
selectionMode Defines the number of allowable selections.
Clicking on a selected item will deselect it.
multiple Allows multiple items to be selected. In this mode the map buttons are hidden.
Example: "selectionMode": "multiple"
user Allows a user to use map buttons to switch between the selection modes.
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 handlebar syntax Defines the tooltip text to display on mouseover of an item returned by the root level filter.
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 root level filter.
visible false The 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.2 mapParameters Field

The "mapParameters" field in Section 2.1.3 is a set of name/value fields defining the properties of the map.

This section lists and describes the name/value fields for defining properties of the map.

2.2.1 Required Customizable Fields

Field Valid Values Description
crossOrigin Used for loaded images. A crossOrigin value is required if using the WebGL renderer or if accessing pixel data from an image server.
It's a way for the webpage to ask the image server for permission to use the image.
User credentials Asks for permission, sending user credentials to the server.
Example: "CrossOrigin" : "jsmith.j53p19f5"
anonymous Asks for permission but don't send extra information.
Example: "crossOrigin": anonymous
null Default value. Do not ask for permission.
Example: "crossOrigin": null
defaultLat Valid latitude The latitude, written as a decimal, at which to initially centre the map field.
Valid latitude values range from 0 to (+/–)90.
Example: "defaultLat": -37.8034619371937
0 Default value. The map field initially centres at latitude 0, the equator.
defaultLong Valid longitude The longitude, written as a decimal, at which to initially centre the map field.
Valid longitude values range from 0 to (+/–)180.
Example: "defaultLon": 144.89993237404
0 Default value. The map field initially centres at longitude 0, the prime meridian running through Greenwich, England.
mapViews Array of map view definitions An array of map view definitions, each defining the properties of a map view. Each map view definition is a set of name/value pair fields, some being required, some being optional.
Section [2.3 mapViews Field] [Section 2.3] lists and describes the fields for defining the properties of a map view.
maxResolution Decimal number The maximum resolution at which the map will be visible.
Example: "maxResolution": 2116.670900008467
??? Default value.
minResolution Decimal number The minimum resolution at which the map will be visible..
Example: "minResolution": 0.21166709000084669
??? Default value.
zoom Integer The level at which to initially zoom the map field.
Example: "zoom": 14
2 Default value.

2.3 mapViews Field

The "mapViews" field in Section 2.2.1 is an array of map view definitions, each defining the visual parameters (e.g. 2D projection, resolution, zoom level) of a map view.

This section lists and describes the fields for defining the properties of a map view.

2.3.1 Required System Fields

Field Valid Values Description
extent ??? ???.
Example: ???
??? Default value.
params Array of map view parameters Set of predefined mapView parameters.
Example: Street map.
"params": {
    "LAYERS": "CARTO_WM",
    "VERSION": "1.1.1",
    "FORMAT": "image/png",
}
Example: Satellite image.
"params": {
    "LAYERS": "AERIAL_WM",
    "VERSION": "1.1.1",
    "FORMAT": "image/png",
}
Example: Satellite imager with street map overlay.
"params": {
    "LAYERS": "CARTO_OVERLAY_WM",
    "VERSION": "1.1.1",
    "FORMAT": "image/png",
}
Example:
"params": {
    "LAYERS": "CARTO_WM",
    "VERSION": "1.1.1",
    "FORMAT": "image/png",
    "HEIGHT": "512",
    "WIDTH": "512",
    "BBOX": "16133701.716224,-4393099.8016821,16446787.78408,-4080013.733826",
    "SRS": "EPSG:3857",
    "STYLES": "",
    "REQUEST": "GetMap",
    "SERVICE": "WMS",
    "FIRSTTILE": true
    }
}
Example:
"params": {
    "LAYERS": "AERIAL_WM",
    "VERSION": "1.1.1",
    "FORMAT": "image/png",
    "HEIGHT": "512",
    "WIDTH": "512",
    "BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
    "SRS": "EPSG:3857",
    "STYLES": "",
    "REQUEST": "GetMap",
    "SERVICE": "WMS",
    "FIRSTTILE": true
    }
}
resolutions ??? ???.
Example: ???
??? Default value.
serverType Defines the map source.
geoserver An open source server for sharing geospatial data. Used for web base maps such as OpenLayers, Google Maps, etc.
Example: "serverType": "geoserver"
tile A server providing maps as tiles i.e. splitting the map up into images.
Example: "serverType": "tile"
tileSize tile dimensions Map tile dimensions (height x width) in pixels, written as an array.
Example:
"tileSize": [
    512,
    512
    ]
??? Default value.
url url address url address to communicate with a map server.
Example: "url": "https://base.maps.vic.gov.au/service"

2.4 layers Field

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

This section lists and describes the fields for defining the properties of a map layer.

2.4.1 Required Customizable Fields

Field Valid Values Description
filter Elastic search query A query to return items (e.g. Sewer Gravity Pipes) for display in the layer.
Example:
"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'}}]}}}"
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.4.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": "green"``
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 Image file number The image to use to indicate point items (e.g. Hydrants) returned by a layer filter.
Example: "imageFileNo": "62435f30-20fc-11e8-8329-0db8fb5fedc2"
Defaults to the existing image.
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 line 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": "<b>SEWER PIPE {{{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 a layer filter.

2.5 selection Field

The "selection" field in Section 2.1.3 is a set of name/value fields defining the display properties of items selected from the map.

This section lists and describes the name/value fields for defining display properties of items selected from the map.

2.5.1 Optional Customizable Fields

Field Valid Values Description
selectionColor A valid color The line colour of selected lines and polygons.
Example: "selectionColor": "blue"
green Default value.
selectionFill A valid color The fill colour of selected polygons.
Example: "selectionFill": "blue"
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 line end style of selected lines and polygons.
square Lines ends are square.
Example: "selectionLineCap": "square"
round Default value. Lines ends are rounded.
selectionLineDash [x,y] The line 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.

 

3 Typical sc-address-map 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':'d62a4970-d88e-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,
            "zoom": 14
    },
    "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.

ROOT LEVEL 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"
        }
    ]