# capture-coordinates

## Overview

{% hint style="info" %}
The `capture-coordinates` component was visually updated in version **4.82.0** of JourneyApps Runtime.
{% endhint %}

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

{% tabs %}
{% tab title="Light Mode" %}
![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-d0322a4c66f6f4805a1332af37cbac87bcdf6c78%2Fcapture-coordinates-light.png?alt=media)
{% endtab %}

{% tab title="Dark Mode" %}
![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-6928fe17f813021df7313b4015e1830bd37a3084%2Fcapture-coordinates-dark.png?alt=media)
{% endtab %}
{% endtabs %}

### 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.

```xml
<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.

```xml
<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)

```xml
<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](#show-markers) for more information on hiding markers.

{% hint style="info" %}
Must be a variable or field of type `location`. See the reference on [data model fields](https://docs.journeyapps.com/reference/build/data-model-configuration/model/field) for more details.
{% endhint %}

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

<capture-coordinates bind="current_location" />
```

### `label`

{% content-ref url="../xml-fields/label" %}
[label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label)
{% endcontent-ref %}

### `required`

{% content-ref url="../xml-fields/required" %}
[required](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/required)
{% endcontent-ref %}

## Advanced Attributes

### `align-content`

{% content-ref url="../xml-fields/align-content" %}
[align-content](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-content)
{% endcontent-ref %}

### `align-controls`

{% hint style="info" %}
**Version compatibility**

`align-controls` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `center`|`left` | `right`

**Default**: `left`

Specify the alignment of the map’s controls. **Note**: controls are visible when the [`allow-zoom`](#allow-zoom) or [`allow-dragging`](#allow-dragging) attributes are enabled.

{% code title="main.view\.xml" %}

```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>
```

{% endcode %}

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2F7VJx5ZGQaLBEQ2m41Ido%2Fimage.png?alt=media&#x26;token=39c85d97-d100-4f0e-ba4c-e2cfda293e99" alt=""><figcaption></figcaption></figure>

### `align-label`

{% content-ref url="../xml-fields/align-label" %}
[align-label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-label)
{% endcontent-ref %}

### `allow-dragging`

{% hint style="info" %}
**Version compatibility**

`allow-dragging` was introduced in version **4.82.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `boolean`

**Default**: `false`

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

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

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

### `allow-zoom`

{% hint style="info" %}
**Version compatibility**

`allow-zoom` was introduced in version **4.82.0** of the JourneyApps Runtime.
{% endhint %}

**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.

{% tabs %}
{% tab title="capture-coordinates" %}
{% code title="main.view\.xml" %}

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

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

{% endcode %}
{% endtab %}

{% tab title="display-coordinates" %}
{% code title="main.view\.xml" %}

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

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

{% endcode %}
{% endtab %}
{% endtabs %}

### `height`

**Optional**

**Type**: `integer`

**Default**: `500`

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

{% tabs %}
{% tab title="capture-coordinates" %}
{% code title="main.view\.xml" %}

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

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

{% endcode %}
{% endtab %}

{% tab title="display-coordinates" %}
{% code title="main.view\.xml" %}

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

<display-coordinates bind="current_location" height="500" />
```

{% endcode %}
{% endtab %}
{% endtabs %}

### `label-case`

{% hint style="info" %}
**Version compatibility**

`label-case` was introduced in version **4.81.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-case" %}
[label-case](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-case)
{% endcontent-ref %}

### `label-color`

{% content-ref url="../xml-fields/label-color" %}
[label-color](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-color)
{% endcontent-ref %}

### `id`

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `on-change`

{% hint style="info" %}
**Version compatibility**

`on-change` was introduced in version **4.82.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/on-change" %}
[on-change](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/on-change)
{% endcontent-ref %}

### `on-location`

{% hint style="info" %}
**Version compatibility**

`on-location` was introduced in version **4.82.0** of the JourneyApps Runtime.
{% endhint %}

**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`](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml) or [navigation](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/view-navigation). See more details:

{% content-ref url="../js-ts-events" %}
[js-ts-events](https://docs.journeyapps.com/reference/build/ui-components/js-ts-events)
{% endcontent-ref %}

{% code title="main.view\.xml" %}

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

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

{% endcode %}

{% code title="main.js" %}

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

{% endcode %}

{% hint style="success" %}
Set `allow-zoom` and `allow-dragging` to `true` to allow users to navigate to different locations on the map.
{% endhint %}

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

### `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.

{% tabs %}
{% tab title="capture-coordinates" %}
{% code title="main.view\.xml" %}

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

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

{% endcode %}
{% endtab %}

{% tab title="display-coordinates" %}
{% code title="main.view\.xml" %}

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

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

{% endcode %}
{% endtab %}
{% endtabs %}

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.captureCoordinates({id:'my-id'})` / `component.displayCoordinates({id:'my-id'})` is called from JS/TS:

### `getMapState`

{% hint style="info" %}
**Version compatibility**

`getMapState` was introduced in version **4.82.0** of the JourneyApps Runtime.
{% endhint %}

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

{% tabs %}
{% tab title="capture-coordinates" %}
{% code title="main.view\.xml" %}

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

{% endcode %}

{% code title="main.js" %}

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

{% endcode %}
{% endtab %}

{% tab title="display-coordinates" %}
{% code title="main.view\.xml" %}

```xml
<display-coordinates id="my-id" bind="current_location" />
```

{% endcode %}

{% code title="main.js" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

### `setMapState`

{% hint style="info" %}
**Version compatibility**

`setMapState` was introduced in version **4.82.0** of the JourneyApps Runtime.
{% endhint %}

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

{% tabs %}
{% tab title="capture-coordinates" %}
{% code title="main.view\.xml" %}

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

{% endcode %}

{% code title="main.js" %}

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

{% endcode %}
{% endtab %}

{% tab title="display-coordinates" %}
{% code title="main.view\.xml" %}

```xml
<display-coordinates id="my-id" bind="current_location" />
```

{% endcode %}

{% code title="main.js" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

### `scrollIntoView`

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