Skip to content

sc-street-address

go-to-typical-definition

sc-street-address-Image-0

1 Purpose

This document is a user guide for the sc-street-address component as of version 5.25.

sc-street-address places a combined street address search field, street address fields and a map field on a form. The street address search field provides the ability to search for and select an address. Searching for and selecting an address will set the street address field values and place a pin on the map to show the location of that street address. Map buttons provide the ability to:

  • Zoom in, zoom out.
  • Centre the map at your current location.
  • Place a pin at a click point on the map and set the street address field values to those of the closest address to the click point.
  • Toggle between map views.
  • 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. Most fields in the tables and/or examples below use a single name/value pair to define a property of the sc-street-address component e.g. "mandatory": true.

    Whereas the fields "geocodeSearchService", `"mapParameters" and "mapViews" require a set of name/value pair fields to define a property of the sc-street-address 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-street-address The component name.

Example:
"componentName": "sc-street-address"

2.2 Required Customizable Fields

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

Example:
"name": "testScStreetAddress"

2.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 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.
dropPinSelectsAddress For each of the valid values below, selecting the button with the pencil icon and clicking on the map will drop a pin at the click point and activate reverse geocoding i.e. retrieve the closest address to where the pin was dropped.
true Set the street address field values to those of the closest address to the click point.
Set the latitude and longitude field values to those of the closest address to the click point.
Position the pin on the map at the latitude and longitude of the closest address to the click point.

Example
"dropPinSelectsAddress": true
false Default value.
Set the street address field values to those of the closest address to the click point.
Set the latitude and longitude field values to those of the click point.
Position the pin on the map at the click point.
enabled false Disables the following fields on the form: "Address" and "Address Search".
Disables the following buttons on the form: "Current Location" and "Select Location".
A Stop icon appears on mouseover of the above fields and buttons.
The "Zoom", "Full Scteen" and "Map View" buttons remain enabled.

Example:
"enabled": false
true Default value. All fields and map 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 3D earth's 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 a projection coordinate system used for rendering a map of the Australian 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 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 An array of geocode service definitions, each defining the properties of a geocode service.
A geocode service provides geocoding and reverse geocoding functionality.
Geocode service providers include Google, Geocode.Farm, Vicmap, PSMA and psmafarm.
See Appendix A: geocodeSearchService Field for a detailed description of the "geocodeSearchService" field.
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 Works in conjunction with the mandatoryValuesArray field.
The street address field displays as mandatory (i.e. label in red text with an asterisk and with each field in the "mandatoryValuesArray" underlined in red).
Saving without a value in a mandatory field, a message prompts the user to enter a value for that field.

Example:
"mandatory": true
false Default value. The field displays as optional (i.e. label in black text).
mandatoryValuesArray Array of fields 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.
The fields that can be defined as mandatory are:
The default mandatory fields are:
  • street
  • suburb
    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.
    maxZoom Integer Example: "maxZoom": "15"
    Defaults to ???.
    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 Integer On entering criteria into the address search field, the number of milliseconds to wait until the address search function is called.

    Example:
    "searchDelay": 1500
    Defaults to the value set in the Environment Configuration document for the "clientConfiguration"."searchDelay" field, or to 500 milliseconds if that isn't set.
    searchMinLength Integer>=3 The minimum number of characters, excluding trailing spaces, that need to be entered into the address search field before the address search function is called.

    Example:
    "searchMinLength": 5
    3 Default value
    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.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.

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

    Example:
    "name": "There needs to be a suburb"
    jsonPathQuery json path query Identifies the field to be defined as mandatory.

    Example:
    "jsonPathQuery": "$..features[?(@.properties.suburb)]"

    3 Typical 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": "Insert your Google API Key here",
                    "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": "CARTO_WM",
                        "REQUEST": "GetMap",
                        "SERVICE": "WMS",
                        "SRS": "EPSG:3857",
                        "STYLES": "",
                        "VERSION": "1.1.1",
                        "WIDTH": "512"
                    },
                    "serverType": "geoserver",
                    "uiLabel": "V",
                    "url": "https://base.maps.vic.gov.au/service"
                },
                {
                    "EPSG": "EPSG:3857",
                    "params": {
                        "BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
                        "FIRSTTILE": true,
                        "FORMAT": "image/png",
                        "HEIGHT": "512",
                        "LAYERS": "AERIAL_WM",
                        "REQUEST": "GetMap",
                        "SERVICE": "WMS",
                        "SRS": "EPSG:3857",
                        "STYLES": "",
                        "VERSION": "1.1.1",
                        "WIDTH": "512"
                    },
                    "serverType": "geoserver",
                    "uiLabel": "S",
                    "url": "https://base.maps.vic.gov.au/service"
                },
                {
                    "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": "AERIAL_WM",
                                "REQUEST": "GetMap",
                                "SERVICE": "WMS",
                                "SRS": "EPSG:3857",
                                "STYLES": "",
                                "VERSION": "1.1.1",
                                "WIDTH": "512"
                           },
                           "serverType": "geoserver",
                           "url": "https://base.maps.vic.gov.au/service"
                        },
                        {
                            "EPSG": "EPSG:3857",
                            "params": {
                                "BBOX": "16446787.78408,-4393099.8016821,16759873.851936,-4080013.733826",
                                "FIRSTTILE": true,
                                "FORMAT": "image/png",
                                "LAYERS": "CARTO_OVERLAY_WM",
                                "HEIGHT": "512",
                                "REQUEST": "GetMap",
                                "SERVICE": "WMS",
                                "SRS": "EPSG:3857",
                                "STYLES": "",
                                "VERSION": "1.1.1",
                                "WIDTH": "512"
                            },
                            "serverType": "geoserver",
                            "url": "https://base.maps.vic.gov.au/service"
                        }
                    ],
                    "uiLabel": "M"
                }
            ]
        },
        "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.

    OPTIONAL CUSTOMIZABLE FIELDS:
        "crossOrigin": "j.smith.j53p19f5",
        "disableSave": true,
        "disableSave": true,
        "dropPinSelectsAddress": true,
        "enabled": false,
        "mandatory": true,
        "mandatoryValuesArray": [
            {
                "name": "There needs to be a street number",
                "jsonPathQuery": "$..features[?(@.properties.streetNo)]"
            },
            {
                "name": "There needs to be a street name",
                "jsonPathQuery": "$..features[?(@.properties.street)]"
            },
            {
                "name": "There needs to be a suburb",
                "jsonPathQuery": "$..features[?(@.properties.suburb)]"
            }
        ],
        "maxZoom": 15,
        "positionMandatory": true,
        "searchDelay": 1500,
        "searchMinLength": 5,
        "visible": true
    

    See Appendix A: geocodeSearchService Field for a detailed description of all "geocodeSearchService" definition fields.

     See Appendix C: mapParameters Field for a detailed description of all "mapParameters" definition fields.

    See Appendix D: mapViews Field for a detailed description of all "mapViews" definition fields.

    4 Examples

    Example 1

    Below is a typical sc-selected 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": "Insert your Google API Key here",
                    "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": "CARTO_WM",
                        "REQUEST": "GetMap",
                        "SERVICE": "WMS",
                        "SRS": "EPSG:3857",
                        "STYLES": "",
                        "VERSION": "1.1.1",
                        "WIDTH": "512"
                    },
                    "serverType": "geoserver",
                    "uiLabel": "V",
                    "url": "https://base.maps.vic.gov.au/service"
                },
                {
                    "EPSG": "EPSG:3857",
                    "params": {
                        "BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
                        "FIRSTTILE": true,
                        "FORMAT": "image/png",
                        "HEIGHT": "512",
                        "LAYERS": "AERIAL_WM",
                        "REQUEST": "GetMap",
                        "SERVICE": "WMS",
                        "SRS": "EPSG:3857",
                        "STYLES": "",
                        "VERSION": "1.1.1",
                        "WIDTH": "512"
                    },
                    "serverType": "geoserver",
                    "uiLabel": "S",
                    "url": "https://base.maps.vic.gov.au/service"
                },
                {
                    "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": "AERIAL_WM",
                                "REQUEST": "GetMap",
                                "SERVICE": "WMS",
                                "SRS": "EPSG:3857",
                                "STYLES": "",
                                "VERSION": "1.1.1",
                                "WIDTH": "512"
                           },
                           "serverType": "geoserver",
                           "url": "https://base.maps.vic.gov.au/service"
                        },
                        {
                            "EPSG": "EPSG:3857",
                            "params": {
                                "BBOX": "16446787.78408,-4393099.8016821,16759873.851936,-4080013.733826",
                                "FIRSTTILE": true,
                                "FORMAT": "image/png",
                                "LAYERS": "CARTO_OVERLAY_WM",
                                "HEIGHT": "512",
                                "REQUEST": "GetMap",
                                "SERVICE": "WMS",
                                "SRS": "EPSG:3857",
                                "STYLES": "",
                                "VERSION": "1.1.1",
                                "WIDTH": "512"
                            },
                            "serverType": "geoserver",
                            "url": "https://base.maps.vic.gov.au/service"
                        }
                    ],
                    "uiLabel": "M"
                }
            ]
        },
        "name": "testScStreetAddress"
    }
    

    Resulting field displayed on the form:

    sc-street-address-Example-1-Image-1

    Resulting field displayed on the form after placing a pin on the map:

    To place a pin at a point on the map:

    1. Click the "pencil" icon
    2. Click on the map at the desired point. This will:
      • Place a pin at a click point on the map.
      • Set the street address field values to those of the closest address to the click point.

    sc-street-address-Example-1-Image-2

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

        "testScStreetAddress": {
            "type": "FeatureCollection",
            "features": [
                {
                    "type": "Feature",
                    "properties": {
                        "type": "street",
                        "unitNo": "",
                        "streetNo": "163",
                        "street": "Barkly Street",
                        "suburb": "Footscray",
                        "postcode": "3011",
                        "locationDescription": "",
                        "country": "",
                        "iconImage": "",
                        "iconSize": "",
                        "state": "Victoria"
                    },
                    "geometry": {
                        "type": "Point",
                        "coordinates": [
                            144.898915,
                            -37.799874
                        ]
                    }
                }
            ]
        }