Skip to content

sc-boundary

This document is a user guide for the sc-boundary component version 5.26, released May 1, 2019.

go-to-typical-definition

sc-boundary-field-Example-1-Image-2

1 Purpose

sc-boundary places a map field on a form with the option to combine the map with an address search and street address fields.

Map buttons provide the ability to draw points, circles, lines, quadrilaterals and polygons on the map, delete a drawing, zoom in, zoom out, toggle full screen and select a view mode (Map, Satellite, Street). Mouseover of a map button will display a button tooltip.

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

2 Definition

sc-boundary 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 below use a single name/value pair to define a property of the sc-boundary component e.g. "mandatory": true.

    Whereas the field "geocodeSearchService" requires a set of name/value pair fields to define a property of the sc-boundary component. The tables below provide a summary description of this field and a link to an Appendix that has the detailed description. The link to this Appendix is also listed below.

2.1 Required System Fields

Field Valid Values Description
componentName sc-boundary The component name.

Example:
"componentName": "sc-boundary"

2.2 Required Customizable Fields

Field Valid Values Description
name Any value written in camel case. Defines the name of the sc-boundary field in the document and database.

Example:
"name": "testScBoundary"

2.3 Optional Customizable Fields

Field Valid Values Description
addressEntry true Display a combined map, address search and street address fields on a form.
Entering a full or partial address in the address search field will return a list of matching addresses. Selecting a returned address will populate the street address fields and will centre and zoom the map on that address.

Example:
"addressEntry": true
false Default value.
Display just the map field on the form.
color Valid colour value The colour for points, lines and polygons drawn on the map.
Colours are specified using predefined color names, colour Hex values or colour RGB values.

Examples:
"color": "red"
"color": "#FF0000"
"color": "rgb(255, 0, 0)"
black Default value.
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 Disables the ability to zoom the map using the mouse wheel.

Example:
"disableMouseWheel": true
false Default value.
Enables the ability to zoom the map using the mouse wheel.
disableSave true Drawing a point, line, polygon, etc on the map does not trigger the Save icon to flash.
Exiting the form without saving a point, line, polygon, etc drawn on the map does not trigger a warning message to display.

Example:
"disableSave": true
false Default value.
Drawing a point, line, polygon, etc on the map does trigger the Save icon to flash.
Exiting the form without saving a point, line, polygon, etc drawn on the map does trigger a warning message to display.
enabled false Address search field, address field, drawing buttons and delete drawing button are disabled, removing the ability to search for or enter and address and to draw or delete points, lines, polygons, etc on the map.
A Stop icon appears on mouseover of address search field, address fields, drawing buttons and delete drawing button.
The buttons to zoom in/out, toggle full screen and select map view remain enabled.

Example:
"enabled": false
true Default value.
Address search, address fields and all buttons (drawing, delete drawing, zoom in/out, toggle full screen and map view) are enabled.
Points, lines, polygons, etc can be drawn or deleted on the map.
A Stop icon does not appear on mouseover of address search field, address fields, drawing buttons or delete drawing button.
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. Examples:
EPSG:3111 is the projection coordinate system used for rendering a 2D map of the state of Victoria (between 140.9500, -39.1500 and 149.9800, -34.0000).

Example:
"EPSG": "EPSG:3111"
EPSG:3857 Defaults to the Web Mercator projection (EPSG:3857) which is used to render a map of the world (between 85.06°S and 85.06°N) for online mapping applications such as Google Maps, OpenStreetMaps, OpenLayers, Bing and ESRI.
fullWidth true The sc-boundary field displays full width on the form.

Example:
"fullWidth": true
false Default value.
The sc-boundary field does not display full width on the form.
geocodeSearchService Array of name/value fields An array of geocode service definitions, each defining the properties of a geocode service.
A geocode service provides geocoding and reverse geocoding functionality.
Note: Reverse geocoding functionality is not a requirement of sc-boundary and hence a geocode service definition needs only to include the name/value fields pertaining to geocoding functionality.
sc-boundary uses thegeocodeSearchService field in conjunction with "addressEntry": true to provide 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 boundary map field as a multiple of a standard height.

Example:
"heightNum": 2
1 Default value.
The height of the boundary map field defaults to 1 standard height.
label Any value Defines the name of the boundary field on the form i.e. the field label.

Example:
"label": "Test sc-boundary"
Defaults to no label is displayed.
mandatory true The sc-boundary field displays as mandatory (i.e. label in red text with an asterisk).
Saving without a value (i.e. drawing a point, line or polygon on the map), a message prompts the user to enter a value for the sc-boundary field.

Example:
"mandatory": true
false Default value.
The field displays as optional (i.e. label in black text).
mapParameters Set of name/value fields A set of name/value pair fields that define the properties of the map.
Section 2.4 mapParameters Field lists and describes the name/value fields for defining the properties of the map.
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 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 sc-boundary field is not visible on the form.

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

2.4 mapParameters Field

 The "mapParameters" field in Section 2.3 Optional Customizable Fields 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.4.1 Optional 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.9563
-37.8 Default value.
defaultLon 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": 145.0407
144.9 Default value.
defaultZoom Integer The level at which to initially zoom the map field.

Example:
"defaultZoom": 15
10 Default value.
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 lists and describes the fields for defining the properties of a map view.

2.4.2 mapViews Field

The "mapViews" field in Section 2.4.1 Optional Customizable Fields 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.

Field Valid Values Description
apiKey Valid API key Your API key, if required by the map server.
Map servers are used to share geospatial data. Examples of map servers are Google and Geoserver.

Example:
"apiKey": "your API key"
serverType The server for sharing geospatial data.
geoserver An open source server for sharing geospatial data. Used for web based maps such as OpenLayers and Bing Maps.

Example:
"serverType": "geoserver"
tile A server providing maps as tiles i.e. splitting the map up into images.

Example:
"serverType": "tile"
google Default value.
Google server for sharing geospatial data.

Example:
"serverType": "google"
url url address to communicate with a particular geoserver for geospatial data.
Vicmap url Vicmap geoserver for geospatial data.

Example:
"url": "https://base.maps.vic.gov.au/service"
Formbird OSM url Formbird geoserver for Open Street Map (OSM) geospatial data.

Example:
"url": "https://osm.formbird.com/tiles/{z}/{x}/{y}.png"

2.4.3 Example

            "mapParameters": {
                "defaultLon": 144.9,
                "defaultLat": -37.8,
                "defaultZoom": 15,
                "mapViews": [
                    {
                        "serverType": "google",
                        "apiKey": "place your google keyid here"
                    }
                ]
            }

3 Typical Definition

When using the Google map server, below is a typical sc-boundary definition, defined with its required fields plus any optional field whose value is typically other than its default value.

        {
            "componentName": "sc-boundary",
            "color": "red",
            "fullWidth": true,
            "heightNum": 2,
            "label": "Test sc-boundary",
            "name": "testScBoundary",
            "mapParameters": {
                "defaultLon": 144.9,
                "defaultLat": -37.8,
                "defaultZoom": 15,
                "mapViews": [
                    {
                        "apiKey": "place your google keyid here",
                        "serverType": "google"
                    }
                ]
            }
        }

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.

            "addressEntry": true,
            "country": "au",
            "disableMouseWheel": true,
            "disableSave": true,
            "enabled": false
            "mandatory": false,
            "searchDelay": 1500,
            "searchMinLength": 5,
            "visible": false

4 Examples

Example 1

sc-boundary defined:

  • With the typically needed fields
  • To use Google for sharing geospatial data.
  • To place a map field on a form.
        {
            "componentName": "sc-boundary",
            "fullWidth": true,
            "name": "test1ScBoundary",
            "label": "Test 1 sc-boundary using google for geospatial data",
            "heightNum": 2,
            "color": "red",
            "mapParameters": {
                "defaultLon": 144.9,
                "defaultLat": -37.8,
                "mapViews": [
                    {
                        "apiKey": "place your google keyid here",
                        "serverType": "google"
                    }
                ],
                "defaultZoom": 15
            }
        }

Resulting field displayed on the form:

sc-boundary-field-Example-1-Image-1

Resulting field displayed on the form after drawing a point, a line, a circle, a polygon and a rectangle:

sc-boundary-field-Example-1-Image-2

Resulting sc-boundary field saved in the document and database:

    "test1ScBoundary": {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        144.88703956604002,
                        -37.798914879250155
                    ]
                },
                "properties": {}
            },
            {
                "type": "Feature",
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        144.89081611633299,
                        -37.79711761294367
                    ]
                },
                "properties": {
                    "radius": 151.0916366374728
                }
            },
            {
                "type": "Feature",
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                144.8918460845947,
                                -37.80027127769669
                            ],
                            [
                                144.8942922592163,
                                -37.79867750696124
                            ],
                            [
                                144.8960947036743,
                                -37.800305187338715
                            ],
                            [
                                144.89399185180662,
                                -37.80033909696519
                            ],
                            [
                                144.89360561370847,
                                -37.80200064959227
                            ],
                            [
                                144.8920606613159,
                                -37.801559833150286
                            ],
                            [
                                144.8918460845947,
                                -37.80027127769669
                            ]
                        ]
                    ]
                },
                "properties": {}
            },
            {
                "type": "Feature",
                "geometry": {
                    "type": "LineString",
                    "coordinates": [
                        [
                            144.89639511108396,
                            -37.79820276009505
                        ],
                        [
                            144.89875545501707,
                            -37.796981968428945
                        ],
                        [
                            144.89982833862302,
                            -37.79874532769305
                        ],
                        [
                            144.90128746032713,
                            -37.797965385517784
                        ]
                    ]
                },
                "properties": {}
            },
            {
                "type": "Feature",
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                144.90077247619627,
                                -37.80244146340335
                            ],
                            [
                                144.90497817993162,
                                -37.80244146340335
                            ],
                            [
                                144.90497817993162,
                                -37.80074601126857
                            ],
                            [
                                144.90077247619627,
                                -37.80074601126857
                            ],
                            [
                                144.90077247619627,
                                -37.80244146340335
                            ]
                        ]
                    ]
                },
                "properties": {}
            }
        ]
    }

Example 2

sc-boundary defined to:

  • Use geoserver for sharing geospatial data.
  • Place a combined map, address search and street address fields in a form.
  • Use PSMA geocode service for geocoding address search field values.
        {
            "componentName": "sc-boundary",
            "addressEntry": true,
            "color": "red",
            "EPSG": "EPSG:4326",
            "fullWidth": true,
            "geocodeSearchService": [
                {
                    "autocompleteUrl": "https://api.psma.com.au/predictive/address?query=",
                    "geocodeUrl": "https://api.psma.com.au/beta/v1/addresses?radius=",
                    "name": "psma",
                    "apiKey": "place your psma keyid here",
                    "addressUrl": "https://api.psma.com.au/predictive/address/"
                }
            ],
            "heightNum": 2,
            "label": "Test sc-boundary 3",
            "name": "testScBoundary3",
            "searchDelay": 1500,
            "searchMinLength": 6,
            "mapParameters": {
                "defaultLat": -37.8,
                "defaultLon": 144.9,
                "defaultZoom": 15,
                "mapViews": [
                    {
                        "serverType": "geoserver"
                    }
                ]
            }
        }

Resulting field displayed on the form:

sc-boundary-field-Example-2-Image-1

Resulting field on the form after entering a partial address in the address search field:

sc-boundary-field-Example-2-Image-2

Resulting field on the form after clicking the first matching address:

The map centers on the selected address.

sc-boundary-field-Example-2-Image-3

Resulting field on the form after saving a drawn boundary:

sc-boundary-field-Example-2-Image-4

Resulting sc-boundary field saved in the document and database:

    "test2ScBoundary": {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "id": 1,
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        0.0013029223623502598,
                        -0.0003409671053873353
                    ]
                },
                "properties": {
                    "icon": "images/marker.png"
                }
            },
            {
                "type": "Feature",
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                0.00130292241968983,
                                -0.0003409710309512093
                            ],
                            [
                                0.0013029264593157925,
                                -0.00034097158851409404
                            ],
                            [
                                0.0013029252632401464,
                                -0.0003409771942841644
                            ],
                            [
                                0.001302921361782192,
                                -0.00034097638447860845
                            ],
                            [
                                0.00130292241968983,
                                -0.0003409710309512093
                            ]
                        ]
                    ]
                },
                "properties": null
            }
        ]
    }