capture-coordinates

Overview

The capture-coordinates component was visually updated in version 4.82.0 of JourneyApps Runtime.

The capture-coordinates component allows users to capture their current location. The captured location will be displayed on a map with a marker.

Light Mode

Dark Mode

Basic Examples

Capture coordinates & markers

The following example shows how GPS location capturing can show a mix between marker-query and marker nodes.

In the example the captured location will be bound to the variable specified in the capture-coordinates bind attribute. Markers are simply locations that are being visually highlighted on a map. This is useful to, for example, show where the captured location is in relation to other points of interest.

<var name="current_location" type="location" />
<var name="markers" type="query:location" />

<capture-coordinates bind="current_location">
    <marker label="You are here" bind="current_location" icon="fa-home" />
    <marker-query query="markers" latitude="{location.latitude}" longitude="{location.longitude}" label="This is an example label" />
</capture-coordinates>

"Foreground" Capturing

The following example shows how GPS location capturing can be performed in the "foreground" i.e. the user sees a map showing how their GPS location is captured.

<var name="current_location" type="location" />
<capture-coordinates label="My Location" bind="current_location" required="false" />

"Background" Capturing

Using the show-if configuration option, it is also possible to capture a GPS location in the background (i.e. the map pictured in the screenshot above is not shown)

<var name="current_location" type="location" />
<capture-coordinates show-if="false" bind="current_location" required="false" />

Standard Attributes

bind

Required

Type: location

Default: unset

The capture-coordinates component uses the GPS location of the device and sets this value on the bind variable/field. This value will update as accuracy increases of the device's GPS location. A marker will autogenerate at the bound location if no <marker /> or <marker-query /> is defined. See show-markers for more information on hiding markers.

Must be a variable or field of type location. See the reference on data model fields for more details.

<var name="current_location" type="location" />

<capture-coordinates bind="current_location" />

label

label

required

required

Advanced Attributes

align-content

align-content

align-controls

Version compatibility

align-controls was introduced in version 4.86.1 of the JourneyApps Runtime.

Optional

Type: center|left | right

Default: left

Specify the alignment of the map’s controls. Note: controls are visible when the allow-zoom or allow-dragging attributes are enabled.

main.view.xml

<columns>
    <column>
        <info>align-controls="center"</info>
        <capture-coordinates align-controls="center" allow-zoom="true" allow-dragging="true" label="">
            <marker label="" latitude="39.7392" longitude="-104.9903" />
        </capture-coordinates>            
    </column>
    <column>
        <info>align-controls="left"</info>
        <capture-coordinates align-controls="left" allow-zoom="true" allow-dragging="true" label="">
            <marker label="" latitude="39.7392" longitude="-104.9903" />
        </capture-coordinates>
    </column>
    <column>
        <info>align-controls="right"</info>
        <capture-coordinates align-controls="right" allow-zoom="true" allow-dragging="true" label="">
            <marker label="" latitude="39.7392" longitude="-104.9903" />
        </capture-coordinates>
    </column>
</columns>

align-label

align-label

allow-dragging

Version compatibility

allow-dragging was introduced in version 4.82.0 of the JourneyApps Runtime.

Optional

Type: boolean

Default: false

Allow panning the map through touch gestures or mouse click-and-drag movements.

<var name="current_location" type="location" />

<capture-coordinates bind="current_location" allow-dragging="true" />

allow-zoom

Version compatibility

allow-zoom was introduced in version 4.82.0 of the JourneyApps Runtime.

Optional

Type: boolean

Default: false

Display the zoom controls on the component and allow changing the zoom level of the map with touch gestures or by scrolling.

capture-coordinates

main.view.xml

<var name="current_location" type="location" />

<capture-coordinates bind="current_location" allow-zoom="true" />

display-coordinates

height

Optional

Type: integer

Default: 500

Specify the height (in pixel) of the capture-coordinates / display-coordinates component.

capture-coordinates

main.view.xml

<var name="current_location" type="location" />

<capture-coordinates bind="current_location" height="500" />

display-coordinates

label-case

Version compatibility

label-case was introduced in version 4.81.0 of the JourneyApps Runtime.

label-case

label-color

label-color

id

id

on-change

Version compatibility

on-change was introduced in version 4.82.0 of the JourneyApps Runtime.

on-change

on-location

Version compatibility

on-location was introduced in version 4.82.0 of the JourneyApps Runtime.

Optional

Default: unset

Triggered when: The user selects a location within the map

Event parameter: $value

Return value: Location object containing the latitude and longitude

on-location is an event that calls a JS/TS $:function or navigation. See more details:

JS/TS Events

main.view.xml

<var name="current_location" type="location" />

<capture-coordinates bind="current_location" on-location="$:onLocation($value)"/> />

main.js

function onLocation(location) {
    console.log(location);
    // Example:
    // Object{latitude: 39.7553694, longitude: -105.0195773}
}

Set allow-zoom and allow-dragging to true to allow users to navigate to different locations on the map.

show-if and hide-if

show-ifhide-if

show-markers

Optional

Type: boolean

Default: true

Show or hide all the markers on the map. show-if/hide-if on individual markers is also available.

capture-coordinates

main.view.xml

<var name="current_location" type="location" />

<capture-coordinates bind="current_location" show-markers="false" />

display-coordinates

Component Methods

The following component methods are available when an id is assigned to the component and component.captureCoordinates({id:'my-id'}) / component.displayCoordinates({id:'my-id'}) is called from JS/TS:

getMapState

Version compatibility

getMapState was introduced in version 4.82.0 of the JourneyApps Runtime.

Programmatically retrieve the current state of the map which will contain the current center and zoom position of the map.

capture-coordinates

main.view.xml

<capture-coordinates id="my-id" bind="current_location" />

main.js

try{
  component.captureCoordinates({id: 'my-id'}).getMapState();
}catch (e) {
  // handle exception here
}

display-coordinates

setMapState

Version compatibility

setMapState was introduced in version 4.82.0 of the JourneyApps Runtime.

Programmatically set the center and/or zoom position of the map to a specific value.

capture-coordinates

main.view.xml

<capture-coordinates id="my-id" bind="current_location" />

main.js

try{
  component.captureCoordinates({id: 'my-id'}).setMapState({
    zoom: 12,
    center: new Location({longitude: -33.00, latitude: -10.00})
  });
}catch (e) {
  // handle exception here
}

display-coordinates

scrollIntoView

Programmatically scroll until the capture-coordinates component is visible in the view.