sc-street-address
This document is a user guide for the sc-street-address component release version 7.1.9.
1 Purpose
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:
- Default values for fields described in the tables below are shown in bold text.
- 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 |
|---|---|---|
| centerOnReverse | true | Clicking the "Pencil" button and then clicking a point on the map will:
Example: "centerOnReverse": true |
| false | Default value. Clicking the "Pencil" button and then clicking a point on the map will:
|
|
| 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 | Changing the sc-street-address field value (i.e. entering, selecting or editing an address) does not trigger the Save icon to flash. Exiting the form without saving changes to the sc-street-address field value does not trigger a warning message to display. In the Angular version of the sc-street-address component, clicking the Save icon will not save the sc-street-address field value to the document. In the AngularJS version of the sc-street-address component, clicking the Save icon will save the sc-street-address field value to the document. Example: "disableSave": true |
| false | Default value. Changing the sc-street-address field value (i.e. entering, selecting or editing an address) does trigger the Save icon to flash. Exiting the form without saving changes to the sc-street-address field value does trigger a warning message to display. In both the Angular and AngularJS versions of the sc-street-address component, clicking the Save icon will save the sc-street-address field value to the document. |
|
| 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 (European Petroleum Survey Group) 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. Example: "EPSG": "EPSG:3111"EPSG:3111 uses a coordinate system PROJECTED from the surface of the sphere or ellipsoid (e.g. Earth's curved surface) to a flat surface. Used for rendering a map of the Australian State of Victoria (between 140.9500, -39.1500 and 149.9800, -34.0000). Example: "EPSG": "EPSG:4326"EPSG: 4326 uses a coordinate system for the surface of a sphere or ellipsoid (e.g. Earth's curved surface). Used by the GPS satellite navigation system and Google Earth for the entire Earth's curved surface (between -180.0000, -90.0000 and 180.0000, 90.0000). |
| 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:
See Section2.4 mandatoryValuesArray Field for detailed description of a mandatory field definition. |
The default mandatory fields are:
|
||
| 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:
Resulting field displayed on the form after placing a pin on the map:
To place a pin at a point on the map:
- Click the "pencil" icon
- 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.
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
]
}
}
]
}