DocumentPicker

Purpose

Consists of the DocumentPicker object that enables capturing media (such as recording audio or video and taking pictures), retrieving various documents from the built-in image, video or audio gallery, as well as retrieving any type of an attachment from any other source that is available in the device's native component. This API mimicks the behaviour of the <input_type=file> HTML5 tag and the HTML Media Capture API, none of which work in the Android WebView.

You can create the DocumentPicker object by using the launchbox.DocumentPicker constructor. The constructor can be used to configure the API by means of passing a map of parameters, which have been described in detail in the Properties section. Referring to the DocumentPicker object without quoting any of the parameters will result in displaying native selections screens for the end user to select what type of file must be captured and from what source.

Note

On iOS, the Document Picker API supports recording media in the following formats:

  • audio: AAC-LC

  • video: MPEG-4/H.264 with AAC-LC audio track

  • images: JPG

Module

This object belongs to the DocumentPicker product module.

Properties

Name Description Type Use
source

Allows you to explicitly specify the source of a picked document. The following values are allowed:

  • "library" - Requires using a media file from the library.

  • "capture" - Requires capturing a new file.

By default this parameter is set to "undefined". Lets the end-user decide, by means of a native menu.

 string optional
type

Defines the type of media requested. The following values are allowed, as well as their combinations, passed as an array:

  • image - Results in capturing an image file.

  • video - Results in capturing of a video.

  • audio - Results in capturing of an audio clip.

By default this parameter is set to "undefined", which means that the picker will attempt to pick any type of document.

 string or array optional
imageParams

Allows you to set the parameters used to pick an image. Consists of the following optional parameters:

  • saveToLibrary - Decides if the file should be saved in a gallery. By default it is set to "false".

  • quality - Allows you to set the quality of a JPG image to be picked. If not provided, an image is picked in its original quality.

  • longerEdge - Decides if the image should be resized proportionally, so that it's longer edge is of the defined length. By default it is set to 0, which means that the image is not resized.

Note

When the device is unable to load the image due to memory limitations, the quality parameter is ignored.

 array optional
videoParams

Allows you to set the parameters used to pick a video clip. Consists of the following optional parameters:

  • saveToLibrary - Decides if the clip should be saved in a gallery. By default it is set to "false".

  • preset - Decides if the clip shoud be converted to a defined format. If not provided, the clip is picked in its original resolution. The following values are allowed:

    • native - The clip is picked in its original resolution.

    • 1080p - the clip is converted to the 1080p format (1920 x 1080 pixels).

    • 720p - the clip is converted to the 720p format (1280 x 720 pixels).

    • 540p - the clip is converted to the 540p format (960 x 540 pixels).

    • 360p - the clip is converted to the 360p format (640 x 360 pixels).

  • maxDuration - Allows you to set the duration of the clip to a specified number of seconds. By default it is set to -1, which means that that duration of the clip is not limited.

 array optional
audioParams

Allows you to set the parameters used to pick an audio clip. Consists of the following parameter:

  • maxDuration - Allows you to set the duration of the clip to a specified number of seconds. By default it is set to -1, which means that that duration of the clip is not limited. On Android, this parameter may be overriden by the settings of an external application.

 array optional

Error codes

Name Description
DocumentPickerInternalError Denotes that an internal error has occurred.
DocumentPickerInUseError Denotes that the object is in use by another operation.
DocumentPickerNoCameraError Denotes that there is no camera available in the device.
DocumentPickerCancelledError Denotes that the operation has been cancelled.

Methods

Name Return type Description
pick promise

The method is responsible for activating the native UI component that records sound or video, takes a picture with the built-in camera, or picks an attachment from any other source that is available.

Related topics

Public API reference
Legal notice | Copyright © 2018 and Confidential to Pegasystems Inc. All rights reserved
PDN | Feedback
Advanced...