Skip to content

sc-street-address

1 Purpose

sc-street-address places a combined street address and map field on a form. Clicking on the map places a pin at the click point and populates the street address fields with the address at the click point. A street address search field provides the ability to search for and select an address. Searching for and selecting an address will populate the street address fields, centre and zoom the map and place a pin on the map at the selected address. Map buttons provide the ability to zoom in, zoom out, centre on current location, select an address, toggle map views and toggle full screen.

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

 

2 Definition

sc-street-address 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-street-address definition.

2.1.1 Required System Fields

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

2.1.2 Required Customizable Fields

Field Valid Values Description
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.
name Any value written in camel case. Defines the name of the street address field in the document and database.
Example: "name": "testScStreetAddress"

2.1.3 Optional Customizable Fields

Field Valid Values Description
country Valid country code Used by the geocode service to improve its performance. E.g. address searches will restrict results to the defined country.
To avoid conflicts, recommend using either this "country" field or the "geocoderDefaultCountry" field within the "geocodeSearchService" field (see below) to specify a country, but not both.
Example: "country": "au"
Defaults to the "geocoderDefaultCountry" if one exists, otherwise no restriction on country.
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 Using the address fields or the select address map button to enter an address does not trigger the Save icon to flash.
Exiting the form without saving the entered street address does not trigger a warning message to display.
Example: "disableSave": true
false Default value. Using the address fields or the select address map button to enter an address does trigger the Save icon to flash.
Exiting the form without saving the entered street address does trigger a warning message to display.
enabled false Disables the "Address" and "Address Search" fields.
A Stop icon appears on mouseover of the "Address" and "Address Search" fields.
The "Zoom", "Current Location", and "Map View" map buttons remain enabled.
??? ISSUE: The "Select Address" map button is not disabled allowing an address to be selected & saved. RECOMMEND: It should be disabled and a Stop icon appears on mouseover.
??? ISSUE: The "Current Location" map button zooms, centres on & displays the selected address pin at the current location and allows it to be saves. RECOMMEND: regardless of the "enabled" true/false setting, the "Current Location" button should only position the map, it should not be used to select an address for saving. I.e. t should just zoom, centre on & display a dedicated icon at the current location. Suggest using the same icon as used on its button i.e. as in Google Maps.
Example: "enabled": false
true Default value. All fields and map buttons are enabled.
fullWidth true The street address field displays full width on the form.
Full width is recommended for the street address field.
Example: "fullWidth": true
false Default value. The street address field does not display full width on the form.
geocodeSearchService A geocode service A geocode service provides geocoding and reverse geocoding functionality.
Geocoding translates a human-readable address into a location on a map.
Reverse geocoding translates a location on the map into a human-readable address.
A geocode service is specified by a set of pre-defined name/value fields.
The "geocodeSearchService" field value is an array with one geocode service.
In the examples below only the "geocoderDefaultState" and "geocoderDefaultCountry" fields areare optional and configurable. These fields are used by the geocode service to improve its performance. E.g. address searches will restrict results to the defined country and/or state.
To avoid conflicts, recommend using either the "country" field (see above) or this "geocoderDefaultCountry" field within the "geocodeSearchService" field to specify a country, but not both.
Example: Google geocode service:
"geocodeSearchService": [
    {
        "apiKey": "AIzaSyDr8ovTk9O_JVvCokeaFE6nzsbhMRBCQm8",
        "autocompleteUrl": "https://maps.googleapis.com/maps/api/place/autocomplete/json?input=",
        "geocodeUrl": "https://maps.googleapis.com/maps/api/geocode/json?latlng=",
        "name": "google"
    }
]
Example: Geocode.Farm geocode service:
"geocodeSearchService": [
    {
        "apiKey": "a2338e05-e3cb425e93ad-109049bfb516",
        "autocompleteUrl": "https://www.geocode.farm/v3/json/forward/?addr=",
        "geocodeUrl": "https://www.geocode.farm/v3/json/reverse/",
        "name": "geocodefarm",
        "geocoderDefaultCountry": "Australia"
    }
]
Example: Vicmaps geocode service:
"geocodeSearchService": [
    {
        "apiKey": "a2338e05-e3cb425e93ad-109049bfb516",
        "autocompleteUrl": "https://api.maps.vic.gov.au/vicmapapi/map/addressSearch?jsoncallback=?&format=json&addressLine=",
        "geocodeUrl": "https://www.geocode.farm/v3/json/reverse/",
        "name": "vicmap",
        "geocoderDefaultState": "Victoria",
        "geocoderDefaultCountry": "Australia"
    }
]
Defaults to the Geocode.Farm geocode service.
heightNum numeric Defines the height of the street address map field as a multiple of a standard height.
Example: "heightNum": 2
1 Default value. The height of the street address map field defaults to 1 standard height.
label Any value Defines the name of the street address field on the form i.e. the field label.
Example: "label": " Test sc-street-address"
Defaults to no label is displayed.
language Valid language code Used by the geocode service to improve its performance.
Example: "language": "en"
Default value is geocode service dependent. E.g. Google Maps will attempt to load the most appropriate language based on the users location or browser settings.
mandatory true The street address field displays as mandatory (i.e. label in red text with an asterisk).
Saving without a value, a message prompts the user to enter a value for the street address field.
Example: "mandatory": true
false Default value. The field displays as optional (i.e. label in black text).
mandatoryFields Array of fields Lists which fields will be considered mandatory when the "mandatory": true field is set.
Example:
"mandatoryFields": [
    "streetNo",
    "street",
    "suburb",
    "street",
    "postcode",
    "locationDescription",
]
Defaults to:
"mandatoryFields": [
    "unitNo",
    "streetNo",
    "street",
    "suburb",
    "street",
    "postcode",
    "state",
    "country"
]
maxZoom ??? ???
Example: "maxZoom": "15"
Defaults to ???.
modified ??? ???.
Example: "modified": false
??? Default value.
noSecondaryAssetSelection true Hide the option to select secondary assets.
Example: "noSecondaryAssetSelection": true
false Default value. Show the option to select secondary assets.
popupAssetSelection true If multiple assets are returned when selecting an asset from the map, the assets are listed as selectable items in a popup menu. Note:
(1) If "singlePrimaryAssetSelection": true, then radio buttons are used to allow a single asset to be selected as the primary asset from the popup menu. Otherwise checkboxes are used to allow multiple assets to be selected as primary assets.
(2) If "noSecondaryAssetSelection": false, then checkboxes are used to allow a multiple assets to be selected as secondary assets from the popup menu. Otherwise the option to select secondary assets is hidden.
(3) To dismiss the popup menu a click outside the menu.
Example: "popupAssetSelection": true
false Default value. Multiple returned assets are not listed as selectable items in a popup menu. Note:
(1) If "singlePrimaryAssetSelection": true, one of the returned assets will be automatically selected as the primary asset. Otherwise all of the returned assets will be automatically selected as primary assets.
(2) If "noSecondaryAssetSelection": false, then all of the returned assets will be automatically selected as secondary assets. Otherwise the option to select secondary assets is hidden.
popupAssetSelectionPrimaryText handlebar syntax Defines the display text for assets when selecting the primary asset(s) in popup menu i.e. this occurs when "popupAssetSelection": true (see above).
Example:
"popupAssetSelectionPrimaryText": "Primary Asset {{{systemHeader.summaryName}}} State {{{operational_state}}}"
popupAssetSelectionSecondaryText handlebar syntax Defines the display text for assets when selecting the secondary asset(s) in popup menu i.e. this occurs when "popupAssetSelection": true (see above).
Example:
"popupAssetSelectionSecondaryText": "Secondary Asset {{{systemHeader.summaryName}}} State {{{operational_state}}}"
positionMandatory true Restricts the entry on an address to the address search field, all other address fields being disabled.
Once an address has been selected, the latitude and longitude fields remain disabled but the other address fields are enabled.
Example: "positionMandatory": true
false Default value. All address fields are enabled.
searchDelay 1500 On entering criteria into the address search field, the number of milliseconds to wait until the address search function is called.
500 Defaults to 500 milliseconds.
searchMinLength Numeric value The minimum number of characters that need to be entered into the address search field before the address search function is called.
3 At least 3 characters need to be entered into the address search field before a search will take place.
tooltipsTimeout numeric Defines the number of seconds an asset mouseover tooltip remains visible.
Example: "tooltipsTimeout": 2
Defaults to remains visible until the mouse is moved over another asset.
visible false The street address field is not visible on the form.
Example: "visible": false
true Default value. The street address field is visible on the form.

2.2 mapParameters Field

The "mapParameters" field in Section 2.1.2 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
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 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.0116670900008467
??? Default value.
zoom Integer The level at which to initially zoom the map field.
Example: "zoom": 10
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 properties 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
EPSG Valid EPSG SRID value EPSG is a spatial coordinate system used to locate geographical entities on a map, a map being a 2D projection of a region of the earth's surface.
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:3857 is the projection coordinate system used for rendering map of the world (between 85.06°S and 85.06°N) in Google Maps, OpenStreetMaps, OpenLayers, etc.
Example: "EPSG": "EPSG:3857"
params Array of mapView parameters Array of mapView parameters predefined by a mapping service such a Vic Maps.
Example:
"params": {
    "LAYERS": "WEB_MERCATOR",
    "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": "SATELLITE_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
    }
}
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"
url url address url address to communicate with a map server.
Example: "url": "http://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms"
Example: "url": ""url": "https://osm.formbird.com/tiles/{z}/{x}/{y}.png""

2.3.2 Required Customizable Fields

Field Valid Values Description
uiLabel Alpha character Defines the label for a map view button.
Example: "uiLabel": "V"

2.3.3 Optional 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
groupView Array of map view definitions Group multiple map views definitions for display purposes.
Example:
"groupView": [
    {
        "params": {
            "LAYERS": "SATELLITE_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
        }
        "EPSG": "EPSG:3857",
        "url": "https://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms",
        "serverType": "geoserver"
    }
    {
        "params": {
            "LAYERS": "HYBRID_MERCATOR",
            "VERSION": "1.1.1",
            "FORMAT": "image/png",
            "HEIGHT": "512",
            "WIDTH": "512",
            "BBOX": "16446787.78408,-4393099.8016821,16759873.851936,-4080013.733826",
            "SRS": "EPSG:3857",
            "STYLES": "",
            "REQUEST": "GetMap",
            "SERVICE": "WMS",
            "FIRSTTILE": true
        }
        "EPSG": "EPSG:3857",
        "url": "https://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms",
        "serverType": "geoserver"
    }
]
isShow true Identifies the initial map view to show on load.
Example: "isShow": true
Defaults to the the first map view of the sc-selected-asset definition.

 

3 Typical sc-street-address Definition

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

{
    "componentName": "sc-street-address",
    "country": "au",
    "fullWidth": true,
    "geocodeSearchService": [
            {
                "geocodeUrl": "https://maps.googleapis.com/maps/api/geocode/json?latlng=",
                "apiKey": "AIzaSyDr8ovTk9O_JVvCokeaFE6nzsbhMRBCQm8",
                "autocompleteUrl": "https://maps.googleapis.com/maps/api/place/autocomplete/json?input=",
                "name": "google"
            }
        ],
    "heightNum": 2,
    "label": "Test sc-address-map",
    "language": "en",
    "mapParameters": {
        "defaultLat": -37.8,
        "defaultLon": 144.9,
        "maxResolution": 2116.670900008467,
        "minResolution": 0.0116670900008467,
        "mapViews": [
            {
                "EPSG": "EPSG:3857",
                "params": {
                    "BBOX": "16133701.716224,-4393099.8016821,16446787.78408,-4080013.733826",
                    "FIRSTTILE": true,
                    "FORMAT": "image/png",
                    "HEIGHT": "512",
                    "LAYERS": "WEB_MERCATOR",
                    "REQUEST": "GetMap",
                    "SERVICE": "WMS",
                    "SRS": "EPSG:3857",
                    "STYLES": "",
                    "VERSION": "1.1.1",
                    "WIDTH": "512"
                },
                "serverType": "geoserver",
                "uiLabel": "V",
                "url": "http://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms"
            },
            {
                "EPSG": "EPSG:3857",
                "params": {
                "BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
                "FIRSTTILE": true,
                "FORMAT": "image/png",
                    "HEIGHT": "512",
                    "LAYERS": "SATELLITE_WM",
                    "REQUEST": "GetMap",
                    "SERVICE": "WMS",
                    "SRS": "EPSG:3857",
                    "STYLES": "",
                    "VERSION": "1.1.1",
                    "WIDTH": "512"
                },
                "serverType": "geoserver",
                "uiLabel": "S",
                "url": "http://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms"
            },
            {
                "serverType": "tile",
                "uiLabel": "O",
                "url": "https://osm.formbird.com/tiles/{z}/{x}/{y}.png"
            },
            {
            "groupView": [
                {
                    "EPSG": "EPSG:3857",
                    "params": {
                        "BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
                        "FIRSTTILE": true,
                        "FORMAT": "image/png",
                        "HEIGHT": "512",
                        "LAYERS": "SATELLITE_WM",
                        "REQUEST": "GetMap",
                        "SERVICE": "WMS",
                        "SRS": "EPSG:3857",
                        "STYLES": "",
                        "VERSION": "1.1.1",
                        "WIDTH": "512"
                    },
                    "serverType": "geoserver",
                    "url": "http://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms"
                },
                {
                    "EPSG": "EPSG:3857",
                    "params": {
                        "BBOX": "16446787.78408,-4393099.8016821,16759873.851936,-4080013.733826",
                        "FIRSTTILE": true,
                        "FORMAT": "image/png",
                        "LAYERS": "HYBRID_MERCATOR",
                        "HEIGHT": "512",
                        "REQUEST": "GetMap",
                        "SERVICE": "WMS",
                        "SRS": "EPSG:3857",
                        "STYLES": "",
                        "VERSION": "1.1.1",
                        "WIDTH": "512"
                    },
                    "serverType": "geoserver",
                    "url": "http://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms"
                }
                ],
                "uiLabel": "M"
                }
            ],
            "zoom": 10
        },
    "maxZoom": 15,
    "name": "testScStreetAddress"
}

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:
    "disableSave": true,
    "tooltipsTimeout":2,
    "noSecondaryAssetSelection":true,
    "popupAssetSelection":true,
    "popupAssetSelectionPrimaryText":"primaryAsset: {{{systemHeader.summaryName}}}",
    "popupAssetSelectionSecondaryText":"secondaryAsset: {{{systemHeader.summaryName}}}",
    "positionMandatory": true,
    "crossOrigin": "j.smith.j53p19f5",
    "disableMouseWheel": true,
    "enabled": false,
    "mandatory": true,
    "mandatoryFields": [
        "country"
    ],
    "searchDelay": 1500,
    "searchMinLength": 5,
    "visible": true


MAPVIEWS OPTIONAL CUSTOMIZABLE FIELDS:
    "crossOrigin": "j.smith.j53p19f5",
    "isShow":true,

 

4 Examples

Example 1

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

 

        {
            "componentName": "sc-street-address",
            "country": "au",
            "disableSave": false,
            "disableMouseWheel": false,
            "enabled": true,
            "fullWidth": true,
            "geocodeSearchService": [
                {
                    "geocodeUrl": "https://maps.googleapis.com/maps/api/geocode/json?latlng=",
                    "apiKey": "AIzaSyDr8ovTk9O_JVvCokeaFE6nzsbhMRBCQm8",
                    "autocompleteUrl": "https://maps.googleapis.com/maps/api/place/autocomplete/json?input=",
                    "name": "google"
                }
            ],
            "label": "Test sc-address-map",
            "language": "en",
            "mandatory": false,
            "mandatoryFields": [
                "country"
            ],
            "mapParameters": {
                "defaultLat": -37.8,
                "defaultLon": 144.9,
                "maxResolution": 2116.670900008467,
                "minResolution": 0.0116670900008467,
                "mapViews": [
                    {
                        "EPSG": "EPSG:3857",
                        "params": {
                            "BBOX": "16133701.716224,-4393099.8016821,16446787.78408,-4080013.733826",
                            "FIRSTTILE": true,
                            "FORMAT": "image/png",
                            "HEIGHT": "512",
                            "LAYERS": "WEB_MERCATOR",
                            "REQUEST": "GetMap",
                            "SERVICE": "WMS",
                            "SRS": "EPSG:3857",
                            "STYLES": "",
                            "VERSION": "1.1.1",
                            "WIDTH": "512"
                        },
                        "serverType": "geoserver",
                        "uiLabel": "V",
                        "url": "http://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms"
                    },
                    {
                        "EPSG": "EPSG:3857",
                        "params": {
                            "BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
                            "FIRSTTILE": true,
                            "FORMAT": "image/png",
                            "HEIGHT": "512",
                            "LAYERS": "SATELLITE_WM",
                            "REQUEST": "GetMap",
                            "SERVICE": "WMS",
                            "SRS": "EPSG:3857",
                            "STYLES": "",
                            "VERSION": "1.1.1",
                            "WIDTH": "512"
                        },
                        "serverType": "geoserver",
                        "uiLabel": "S",
                        "url": "http://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms"
                    },
                    {
                        "crossOrigin": null,
                        "serverType": "tile",
                        "uiLabel": "O",
                        "url": "https://osm.formbird.com/tiles/{z}/{x}/{y}.png"
                    },
                    {
                        "groupView": [
                            {
                                "EPSG": "EPSG:3857",
                                "params": {
                                    "BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
                                    "FIRSTTILE": true,
                                    "FORMAT": "image/png",
                                    "HEIGHT": "512",
                                    "LAYERS": "SATELLITE_WM",
                                    "REQUEST": "GetMap",
                                    "SERVICE": "WMS",
                                    "SRS": "EPSG:3857",
                                    "STYLES": "",
                                    "VERSION": "1.1.1",
                                    "WIDTH": "512"
                                },
                                "serverType": "geoserver",
                                "url": "http://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms"
                            },
                            {
                                "EPSG": "EPSG:3857",
                                "params": {
                                    "BBOX": "16446787.78408,-4393099.8016821,16759873.851936,-4080013.733826",
                                    "FIRSTTILE": true,
                                    "FORMAT": "image/png",
                                    "LAYERS": "HYBRID_MERCATOR",
                                    "HEIGHT": "512",
                                    "REQUEST": "GetMap",
                                    "SERVICE": "WMS",
                                    "SRS": "EPSG:3857",
                                    "STYLES": "",
                                    "VERSION": "1.1.1",
                                    "WIDTH": "512"
                                },
                                "serverType": "geoserver",
                                "url": "http://api.maps.vic.gov.au/vicmapapi-mercator/map-wm/wms"
                            }
                        ],
                        "uiLabel": "M"
                    }
                ],
                "zoom": 10
            },
            "maxZoom": 15,
            "name": "testScStreetAddress",
            "positionMandatory": true,
            "visible": true
        }

Resulting field displayed on the form:

alt text

Resulting field displayed on the form after after entered data:

alt text

Resulting sc-street-address field saved in the database:

"testScStreetAddress": "Orange"