Skip to content

sc-boundary

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

1 Purpose

This document is a user guide for the sc-boundary component as of version 5.20.

sc-boundary can be defined to place either a map field or a combined map, address search and street address fields on a form.

Map buttons provide the ability to zoom in, zoom out, select, draw points, draw lines, draw polygons, draw a point at current location, delete a drawing and toggle full screen. Mouseover of a map button will display the tooltip for that button.

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.1 Root Level Fields

This section describes the root level fields of the sc-boundary definition.

2.1.1 Required System Fields

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

2.1.2 Required Customizable Fields

Field Valid Values Description
name Any value written in camel case. Defines the name of the boundary field in the document and database.
Example: "name": "testScBoundary"

2.1.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 colour value The colour for points, lines and polygons, etc drawn on the map.
Examples:
"color": "darkRed"
"color": "#8B0000"
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.
Example: "country": "au"
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 sc-boundary 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 sc-boundary 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 All sc-boundary field drawing buttons are disabled, removing the ability to draw points, lines, polygons, etc on the map.
A Stop icon appears on mouseover of any sc-boundary field drawing buttons.
The zoom in/out and address search functionality remains enabled.
Example: "enabled": false
true Default value.
All sc-boundary field drawing buttons are enabled.
Points, lines, polygons, etc can be drawn on the map.
A Stop icon does not appear on mouseover of any sc-boundary field drawing buttons.
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).
EPSG:4326 is the projection coordinate system used for rendering the WGS84 3D model of the entire earth as a 2D map (between -180.0, -90.0 and 180.0, 90.0).
Example:
"EPSG": "EPSG:3111"
"EPSG": "EPSG:4326"
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 sc-boundary field displays full width on the form.
Example: "fullWidth": true
false Default value.
The boundary field does not display full width on the form.
geocodeSearchService Array of name/value fields An array of name/value fields defining the properties of 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.
Reverse geocoding functionality is not a requirement of sc-boundary and hence the geocodeSearchService field needs only include the name/value fields pertaining to geocoding functionality.
sc-boundary uses thegeocodeSearchService field in conjunction with "addressEntry": true and "serverType": "geoserver" to provide geocoding functionality.
Example:
Example 2 in Section 4 Examples shows a geocodeSearchService field defined in conjunction with "addressEntry": true and "serverType": "geoserver".
In this example, the geoSearchService has been defined to use the PSMA geocode service for geocoding a value entered in the address search 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, 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 fields defining the properties of the map.
Section 2.2 mapParameters Field lists and describes the name/value fields for defining the properties of the map.
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.
Example: "searchMinLength": 5
3 At least 3 characters need to be entered into the address search field before a search will take place.
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.2 mapParameters Field

 The "mapParameters" field in Section 2.1.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.2.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.8
24.667 Default value. The map field initially centres at latitude 24.667, the parallel (line of latitude) running through the middle of Australia.
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": 144.9
133.825 Default value. The map field initially centres at longitude 133.825, the meridian (line of longitude) running through the middle of Australia.
defaultZoom Integer The level at which to initially zoom the map field.
Example: "defaultZoom": 15
2 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.3 mapViews Field

The "mapViews" field in Section 2.2.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.

2.3.1 Optional Customizable Fields

Field Valid Values Description
apiKey Valid API key Your API key for 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 base maps such as OpenLayers.
Example: "serverType": "geoserver"
google Default value.
Google server for sharing geospatial data.
Example: "serverType": "google"

 

3 Typical sc-boundary 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": "AIzaSyBtFZmD57h3TyoM7cvuvQikEIG2uJaZgko",
                        "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": "aF3mi48uMRGD6iX6VCGRQIo29bu2C6uR",
                    "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
            }
        ]
    }