# capture-signature

## Overview

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

The `capture-signature` component was visually updated in version **4.74.0** of the JourneyApps Runtime.
{% endhint %}

Allows users to capture a signature digitally.

### Using signatures

Signatures are captured as SVG's with a path that describes it. That path can be accessed using toText():

```javascript
// Get the SVG text of the signature as XML
// Assuming the name of the signature is `captured_sig`
var signatureSVG = view.captured_sig.toText();
```

Signatures can also be printed using a Zebra bluetooth printer ([see docs](https://docs.journeyapps.com/reference/build/integration/journeyapps-print-android)) directly from version 4.34.4 of the JourneyApps Container. The Zebra printer uses a language called ZPL, so we can convert the signature to ZPL by using:

```javascript
// Get the SVG text of the signature as ZPL
// Assuming the name of the signature is `captured_sig`
var signatureSVG = view.captured_sig.toZPL();
```

### Basic Example

```xml
<var name="my_signature" type="signature" />

<capture-signature label="Add a signature" bind="my_signature" required="true" />
```

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FxCQ52rQQ9tlYAVVqLFT1%2Fcapture-signature-example.png?alt=media\&token=8dcf1162-a25c-4dd5-9a1c-e2368c9c4e51)

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2F6r4nDdXahFC12dJ8QpTs%2Fcapture-signature-example-open.png?alt=media\&token=40f5de75-0434-4c25-b90a-83c567d7fbd2)

## Standard Attributes

### `bind`

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

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

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

### `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 %}

### `control-order`

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

### `dialog-title`

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

`dialog-title` was introduced in version **4.88.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type:** `string` (static text, a [format string](https://docs.journeyapps.com/reference/app-features/xml-format-strings) or the return value of a [JS/TS function](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml))

**Default**: "Sign here"

Override the title that is displayed at the top of the dialog when capturing a signature.

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

```xml
<capture-signature label="Add a signature" bind="my_signature" dialog-title="Custodian signature" required="true" />   
```

{% endcode %}

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FMOiDM0CQDZMRwzEg6Yo1%2Fcapture-signature-dialog-title.png?alt=media\&token=709841f2-9489-44ee-ab01-57aca93ee7ca)

### `disabled`

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

### `fullwidth`

**Optional**

**Type**: `boolean`

**Default**: `false`

Specify whether the signature preview should span the full width of the available screen space.

{% tabs %}
{% tab title="capture-signature" %}

```xml
<capture-signature bind="authorization_sig" label="Authorized" fullwith="true"/>
```

{% endtab %}

{% tab title="display-signature" %}

```xml
<capture-signature bind="authorization_sig" label="Authorized" fullwith="true"/>
```

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-276fd3ac63e476b3ebc3ab271f6a5ca3aa77e2e1%2Fcapture-signature-fullwidth.png?alt=media)
{% endtab %}
{% endtabs %}

### `icon-position`

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

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

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

### `id`

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

### `label-case`

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

`label-case` was introduced in version **4.80.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 %}

### `on-change`

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

### `orientation`

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

* `orientation` was introduced in version **4.88.0** of the JourneyApps Runtime and is supported on mobile platforms: Android and iOS.
* Container version **23.5.1** or later is required for this feature on iOS, and is recommended for Android.
  {% endhint %}

**Optional**

**Type**: `auto` | `landscape` | `portrait`

**Default**: `auto`

Lock the orientation of the draw-pad for capturing a signature.

When `orientation` is set to `landscape` or `portrait`, the draw-pad will always display in the specified orientation, regardless of the orientation of the device. When `orientation` is set to `auto`, or not specified, the orientation of the draw-pad mirrors the orientation of the device.

### `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 %}

## 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.captureSignature({id:'my-id'})` / `component.displaySignature({id:'my-id'})` is called from JS/TS:

### `captureMedia`

Programmatically open the signature dialog that allows the user to sign.

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

### `closeMedia`

Programmatically close the signature preview.

{% tabs %}
{% tab title="capture-signature" %}

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

{% endtab %}

{% tab title="display-signature" %}

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

{% endtab %}
{% endtabs %}

### `deleteMedia`

Programmatically clear a captured signature.

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

{% hint style="warning" %}
`deleteMedia` will trigger an [`on-change`](#on-change) if a function is assigned to it.
{% endhint %}

### `openMedia`

Programmatically open the signature preview.

{% tabs %}
{% tab title="capture-signature" %}

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

{% endtab %}

{% tab title="display-signature" %}

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

{% endtab %}
{% endtabs %}

### `scrollIntoView`

Programmatically scroll until the `capture-signature` / `display-signature` component is visible in the view.

{% tabs %}
{% tab title="capture-signature" %}

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

{% endtab %}

{% tab title="display-signature" %}

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

{% endtab %}
{% endtabs %}