Card

The Card object contains methods that invoke cards.

Installation:

To use this API in your project, add the invoke card plugin:

webworks plugin add com.blackberry.invoke.card

Learning Resources:

Sample - Invocation Sample that demonstrates how to invoke apps and how to create an invocable app [BlackBerry on GitHub].

Sample - Share-Targets Sample that demonstrates how to invoke a list of Share Targets. [BlackBerry on GitHub].

invokeCalendarComposer()

Invokes calendar event composer card.

Synopsis:

void blackberry.invoke.card.invokeCalendarComposer(options, onDone, onCancel, onInvoke)

Parameters:

options {CalendarComposerOptions}

An object of type {CalendarComposerOptions} which describes all options available to the event composer.

onDone {Function}

The callback function that will be triggered when the user finished with the event composer.

data {String}

The data string back from the event composer.

onCancel {Function}

The callback function that will be triggered if the user cancels the event composer.

reason {String}

A String that describes the reason the event composer was cancelled.

onInvoke {Function}

The callback function that will be triggered when the event composer is invoked.

error {String}

A String that describes if there was an error. No error will be returned on success.

Example:

<script type="text/javascript">

    //simply invoke calendar composer, with no options and callbacks
    blackberry.invoke.card.invokeCalendarComposer();

    //invoke calendar event composer with subject, body, participants, startTime and duration options
    blackberry.invoke.card.invokeCalendarComposer({
        subject: "Event Name",
        body: "Notes about this event",
        participants: ["a@a.ca", "b@b.com"],
        startTime: "Wed Jun 25 11:00:00 2012",
        duration: 30
    }, function (done) {
        console.log(done);
    }, function (cancel) {
        console.log(cancel)
    }, function (invokeError) {
        console.log(invokeError);
    });

</script>
            

invokeCalendarPicker()

Invokes calendar event picker card. Note: Filepaths using the local:/// protocol are not supported for this card.

Synopsis:

blackberry.invoke.card.invokeCalendarPicker(options, onDone, onCancel, onInvoke)

Parameters:

options {CalendarPickerOptions}

An object of type {CalendarPickerOptions} which describes all options available to the event picker.

onDone {Function}

The callback function that will be triggered when the user finished with the event picker.

data {String}

The data string back from the event picker.

onCancel {Function}

The callback function that will be triggered if the user cancel the event picker.

reason {String}

A String that describes the reason the event picker was cancelled.

onInvoke {Function}

The callback function that will be triggered when the event picker is invoked.

error {String}

A String that describes if there was an error. No error will be returned on success.

Example:

<script type="text/javascript">

    //simply invoke calendar picker, with no options and callbacks
    blackberry.invoke.card.invokeCalendarPicker();

    //invoke calendar event picker with filepath option
    blackberry.invoke.card.invokeCalendarPicker({filepath: "/path/to/file.vcs"}, function (done) {
        console.log(done);
    }, function (cancel) {
        console.log(cancel)
    }, function (invokeError) {
        console.log(invokeError);
    });

</script>
            

invokeCamera()

Invokes the Camera Card.

Synopsis:

void blackberry.invoke.card.invokeCamera(mode, onSave, onCancel, onInvoke)

Parameters:

mode {String}

A string to specify the photo video or full mode.

onSave {Function}

The callback function that will be triggered if the user saves a picture or video.

path {String}

A String that describes the path of the file saved.

onCancel {Function}

The callback function that will be triggered if the user does not save and simply quits the camera.

reason {String}

A String that describes the reason the camera was cancelled.

onInvoke {Function}

The callback function that will be triggered when the camera is invoked.

error {String}

A String that describes if there was an error. No error will be returned on success.

Example:

<script type="text/javascript">

    function invokeCameraCard() {
        var mode = blackberry.invoke.card.CAMERA_MODE_PHOTO;
        blackberry.invoke.card.invokeCamera(mode, function (path) {
            alert("saved "+ path);
            },
            function (reason) {
                alert("cancelled " + reason);
            },
            function (error) {
                if (error) {
                    alert("invoke error "+ error);
                } else {
                    console.log("invoke success " );
                }
        });
    }

</script>
            

invokeEmailComposer()

Invokes the email composer card. Note: Filepaths using the local:/// prototcol are supported for this card.

Synopsis:

void blackberry.invoke.card.invokeEmailComposer(options, onDone, onCancel, onInvoke)

Parameters:

options {EmailComposerOptions}

An object of type {EmailComposerOptions} which describes all options available to the email composer.

onDone {Function}

The callback function that will be triggered when the user finished with the email composer.

data {String}

The data string back from the email composer.

onCancel {Function}

The callback function that will be triggered if the user cancels the email composer.

reason {String}

A String that describes the reason the email composer was cancelled.

onInvoke {Function}

The callback function that will be triggered when the email composer is invoked.

error {String}

A String that describes if there was an error. No error will be returned on success.

Example:

<script type="text/javascript">

    //simply invoke email composer, with no options and callbacks
    blackberry.invoke.card.invokeEmailComposer();

    //invoke email composer with subject, body, to, cc and attachment options
    blackberry.invoke.card.invokeEmailComposer({
        subject: "Email subject",
        body: "Email body",
        to: ["a@a.ca", "b@b.com"],
        cc: ["c@c.ca, d@d.com"],
        attachment: ["/path/to/an/attachment.txt", "path/to/another/attachment.txt"]
    }, function (done) {
        console.log(done);
    }, function (cancel) {
        console.log(cancel)
    }, function (invokeError) {
        console.log(invokeError);
    });

</script>
            

invokeFilePicker()

Invokes the FilePicker Card.

Synopsis:

void blackberry.invoke.card.invokeFilePicker(options, onDone, onCancel, onInvoke)

Parameters:

options {FilePickerOptions}

An object to type {FilePickerOptions} describe all the options available for FilePicker.

onDone {Function}

The callback function that will be triggered if the user selects file(s) or folder(s).

pathArray {[String]}

An Array that describes the path of each of the files saved.

onCancel {Function}

The callback function that will be triggered if the user does not select file(s) or folder(s) and simply cancels.

reason {String}

A String that describes the reason the FilePicker was cancelled.

onInvoke {Function}

The callback function that will be triggered when the FilePicker card is invoked.

error {String}

A String that describes if there was an error. No error will be returned on success.

Example:

<script type="text/javascript">

    //invoke the filePicker Card
    function invokeFilePicker(details) {
         blackberry.invoke.card.invokeFilePicker(details, function (path) {
                  alert("saved "+ path);
              },
              function (reason) {
                  alert("cancelled " + reason);
              },
              function (error) {
                  if (error) {
                      alert("invoke error "+ error);
                  } else {
                      console.log("invoke success " );
                  }
              }
          );
    }

    //pick a file of picture or music type
    function invokeFileInPickerMode0() {
     var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_PICKER,
              type: [blackberry.invoke.card.FILEPICKER_TYPE_PICTURE, blackberry.invoke.card.FILEPICKER_TYPE_MUSIC]
          };
      invokeFilePicker(details);
    }

    //pick a file of picture with image crop enabled
    function invokeFileInPickerMode1() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_PICKER,
              type: [blackberry.invoke.card.FILEPICKER_TYPE_PICTURE],
              imageCropEnabled: true
          };
      invokeFilePicker(details);
    }

    //pick a file using a filter, of only jpg and mp4
    function invokeFileInPickerMode2() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_PICKER,
              filter: ["*.jpg", "*.mp4"]
          };
      invokeFilePicker(details);
    }

    //open file picker in GridView and sort by descending name
    function invokeFileInPickerMode3() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_PICKER,
              viewMode: blackberry.invoke.card.FILEPICKER_VIEWER_MODE_GRID,
              sortBy: blackberry.invoke.card.FILEPICKER_SORT_BY_NAME,
              sortOrder: blackberry.invoke.card.FILEPICKER_SORT_ORDER_DESCENDING
          };
      invokeFilePicker(details);
    }

    //open file picker in multiple mode with a title in viewMode list
    function invokeFileInPickerMode4() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_PICKER,
              viewMode: blackberry.invoke.card.FILEPICKER_VIEWER_MODE_LIST,
              title: "Some Custom Title"
          };
      invokeFilePicker(details);
    }

    //open file picker in multiple mode at SHARED FOLDER
    function invokeFileInPickerMode5() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_PICKER,
              directory: [blackberry.io.sharedFolder]
          };
      invokeFilePicker(details);
    }

    //open file picker in saver mode at SHARED FOLDER
    function invokeFileInPickerMode6() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_PICKER_MULTIPLE,
              directory: [blackberry.io.sharedFolder]
          };
      invokeFilePicker(details);
    }

    //open file picker in saver mode at SHARED FOLDER.
    function invokeFileInPickerMode7() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_SAVER,
              directory: [blackberry.io.sharedFolder]
          };
      invokeFilePicker(details);
    }

    //open file picker in saver mode and allow overwrite - try to save already saved file
    function invokeFileInPickerMode8() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_SAVER,
              directory: [blackberry.io.sharedFolder],
              allowOverwrite: true
          };
      invokeFilePicker(details);
    }

    //open file picker in multiple saver mode to save a folder path
    function invokeFileInPickerMode9() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_SAVER_MULTIPLE,

          };
      invokeFilePicker(details);
    }

    //open file picker in  saver mode with single file name
    function invokeFileInPickerMode10() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_SAVER,
              defaultSaveFileNames: ["file1.jpg"]
          };
      invokeFilePicker(details);
    }

    //open file picker in multiple saver mode with file names and file types
    function invokeFileInPickerMode11() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_SAVER_MULTIPLE,
              defaultSaveFileNames: ["file1.jpg", "file2.jpg"]
          };
      invokeFilePicker(details);
    }

    //open file picker in single  mode with a type and defaultType
    function invokeFileInPickerMode12() {
      var details = {
              mode: blackberry.invoke.card.FILEPICKER_MODE_PICKER,
              type: [blackberry.invoke.card.FILEPICKER_TYPE_PICTURE,
                     blackberry.invoke.card.FILEPICKER_TYPE_DOCUMENT],
              defaultType: blackberry.invoke.card.FILEPICKER_TYPE_DOCUMENT
          };
      invokeFilePicker(details);
    }


</script>
            

invokeIcsViewer()

Invokes the IcsViewer Card to display an iCalendar (.ics) event.

Synopsis:

blackberry.invoke.card.invokeIcsViewer(options, onDone, onCancel, onInvoke)

Parameters:

options {IcsViewerOptions}

An object to type {IcsViewerOptionsIcsViewerOptions} describes all the options available for IcsViewer.

onDone {Function}

The callback function that will be triggered when the event is added to a calendar.

data {String}

A data string that might be empty or to contain some information.

onCancel {Function}

The callback function that will be triggered when the card invocation has been cancelled.

reason {String}

A String that describes the reason the IcsViewer was cancelled.

onInvoke {Function}

The callback function that will be triggered when the IcsViewer card is invoked.

error {String}

A String that describes if there was an error. No error will be returned on success.

Example:

<script type="text/javascript">

    //invoke the IcsViewer Card
    function invokeIcsViewer(options) {
      blackberry.invoke.card.invokeIcsViewer(options, function (data) {
            alert("Card is done");
          },
          function (reason) {
            alert("cancelled " + reason);
          },
          function (error) {
            if (error) {
              alert("invoke error "+ error);
            } else {
              console.log("invoke success " );
            }
          }
      );
    }


    //invoke IcsViewer with no account id provided
    function invokeIcsViewerNoAccountId() {
      var options = {
        uri: "file:///accounts/1000/shared/documents/test.ics"
      };

      invokeIcsViewer(options);
    }

    //invoke IcsViewer with an account id provided
    function invokeIcsViewerWithAccountId() {
      var options = {
        uri: "file:///accounts/1000/shared/documents/test.ics",
        accountId: 1
      };

      invokeIcsViewer(options);
    }

</script>
            

invokeMediaPlayer()

Invokes the MediaPlayer Card.

Synopsis:

void blackberry.invoke.card.invokeMediaPlayer(options, onDone, onCancel, onInvoke)

Parameters:

options {MediaPlayerOptions}

An object to type MediaPlayerOptions describe all the options available for media player.

onDone {Function}

The callback function that will be triggered when the user finished with the media player.

data {String}

he data string back from the media player.

onCancel {Function}

The callback function that will be triggered if the user cancel the media player.

reason {String}

A String that describes the reason the MediaPlayer was cancelled.

onInvoke {Function}

The callback function that will be triggered when the MediaPlayer card is invoked.

error {String}

A String that describes if there was an error. No error will be returned on success.

Example:

<script type="text/javascript">

    //invoke the mediaPlayer Card
    function invokeMediaPlayer(options) {
      blackberry.invoke.card.invokeMediaPlayer(options, function (data) {
          alert("Done: "+ data);
        },
        function (reason) {
          alert("cancelled: " + reason);
        },
        function (error) {
          if (error) {
            alert("invoke error "+ error);
          } else {
            console.log("invoke success");
          }
        }
      );
    }


    //Invoke media player with the only title set.
    function invokeMediaPlayerWithTitle() {
      var options = {
        contentTitle: "Just Title",
      };

      invokeMediaPlayer(options);
    }

    //Invoke media player with title and video.
    function invokeMediaPlayerTitleAndVideo() {
      var options = {
        contentTitle: "My First Record",
        contentUri: "file:///accounts/1000/shared/camera/VID_00000001.mp4"
      };

      invokeMediaPlayer(options);
    }

    //Invoke media player with title, audio and a background image.
    function invokeMediaPlayerTitleAudioAndImage() {
      var options = {
        contentTitle: "My First Record",
        contentUri: "file:///accounts/1000/shared/camera/AUD_00000001.m4a,
        imageUri: "local:///Background4MediaPlayerAudio.jpg"
      };

      invokeMediaPlayer(options);
    }

</script>
            

invokeTargetPicker()

Invokes the Target Picker Card

Synopsis:

void blackberry.invoke.card.invokeTargetPicker(request, title, onSuccess, onError)

Parameters:

request {Object}

Object literal that specifies what to invoke. None of the fields are required. Refer to the example code for more information.

action {String}

The action to be performed by the target.

mime {String}

MIME type of data to be acted on. If the MIME type is not specified then the mime type would be inferred from the given URI. If the MIME type cannot be inferred or URI field is empty then invocation will be rejected.

uri {String}

URI pointing to invocation data. If no URI is provided then this implies that the invocation data is provided in-band in the data field of the invocation request.

data {String|Blob}

Data (String or Blob) to be acted upon encoded based on the specified type. NOTE: If a String is passed, make sure that it does not contain unicode characters or invocation will fail.

title {String}

The title string that should appear at the top of the target picker card.

onSuccess {Function}

A callback that is called on successfull invocation of a target.

onError {Function}

A callback function that will be triggered on error during the invocation process.

Example:

<script type="text/javascript">

    function onInvokeSuccess (msg) {
        console.log("Invocation Success" + msg);
    }

    function onInvokeError (msg) {
        console.log("Invocation Error: " + msg);
     }

    function shareCardPNG() {
        var request = {
                action : 'bb.action.SHARE',
                uri : 'local:///test_image.png',
                target_type: ["CARD"]
            };

         blackberry.invoke.card.invokeTargetPicker(request, "Share Card JPEG", onInvokeSuccess, onInvokeError);
    }

    function shareCardFilePNG() {
        var request = {
            action : 'bb.action.SHARE',
            uri : 'file://' + blackberry.io.sharedFolder  + '/../app/native/manual/InvocationTest/test_image.png',
            target_type: ["CARD"]
        };

        blackberry.invoke.card.invokeTargetPicker(request, "Share JPEGS Card", onInvokeSuccess, onInvokeError);
    }

    function sharePNG() {
        var request = {
            action : 'bb.action.SHARE',
            uri : 'local:///test_image.png',
            target_type: ["APPLICATION", "VIEWER", "CARD"]
        };

        blackberry.invoke.card.invokeTargetPicker(request, "Shared PNG", onInvokeSuccess, onInvokeError);
    }

    function sharePDFURI() {
        var request = {
            action : 'bb.action.SHARE',
            uri : 'local:///test.pdf',
            target_type: ["APPLICATION", "VIEWER"]
        };

        blackberry.invoke.card.invokeTargetPicker(request, "Shared PDF", onInvokeSuccess, onInvokeError);
    }

    function shareDocURI() {
        var request = {
            action : 'bb.action.SHARE',
            uri : 'local:///test.docx',
            target_type: ["APPLICATION", "VIEWER", "CARD"]
        };

        blackberry.invoke.card.invokeTargetPicker(request, "Share Word Document", onInvokeSuccess, onInvokeError);
    }

    function shareRemoteURL() {
        var request = {
            action : 'bb.action.SHARE',
            uri : 'http://google.com',
            target_type: ["APPLICATION", "VIEWER", "CARD"]
        };

        blackberry.invoke.card.invokeTargetPicker(request, "Shared Remote URL", onInvokeSuccess, onInvokeError);
    }

    function shareTextMockingSelection() {
        var request = {
            action : 'bb.action.SHARE',
            mime : 'text/plain',
            data : 'Some awesome text',
            target_type: ["VIEWER", "CARD"]
        };

        blackberry.invoke.card.invokeTargetPicker(request, "Sharing Text", onInvokeSuccess, onInvokeError);
    }

</script>
            

CAMERA_MODE_FULL

Describes the full mode for camera which means photo,video and TimeShift.

Synopsis:

constant
String blackberry.invoke.card.CAMERA_MODE_FULL = "full"

CAMERA_MODE_PHOTO

Describes the photo mode for camera.

Synopsis:

constant
String blackberry.invoke.card.CAMERA_MODE_PHOTO = "photo"

CAMERA_MODE_VIDEO

Describes the video mode for camera.

Synopsis:

constant
String blackberry.invoke.card.CAMERA_MODE_VIDEO = "video"

FILEPICKER_MODE_PICKER

Describes the picker mode for the FilePicker, allows picking a file.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_MODE_PICKER = "Picker"

FILEPICKER_MODE_PICKER_MULTIPLE

Describes the multiple picker mode for the FilePicker, allows picking multiple files.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_MODE_PICKER_MULTIPLE = "PickerMultiple"

FILEPICKER_MODE_SAVER

Describes the saver mode for the FilePicker, allows saving a file.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_MODE_SAVER = "Saver"

FILEPICKER_MODE_SAVER_MULTIPLE

Describes the multiple saver mode for the FilePicker, allows saving multiple files.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_MODE_SAVER_MULTIPLE = "SaverMultiple"

FILEPICKER_SORT_BY_DATE

Describes the sort by field date.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_SORT_BY_DATE = "Date"

FILEPICKER_SORT_BY_NAME

Describes the sort by field name.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_SORT_BY_NAME = "Name"

FILEPICKER_SORT_BY_SIZE

Describes the sort by field size.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_SORT_BY_SIZE = "Size"

FILEPICKER_SORT_BY_SUFFIX

Describes the sort by field suffix.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_SORT_BY_SUFFIX = "Suffix"

FILEPICKER_SORT_ORDER_ASCENDING

Describes the sort order of ascending.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_SORT_ORDER_ASCENDING = "Ascending"

FILEPICKER_SORT_ORDER_DESCENDING

Describes the sort order of descending.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_SORT_ORDER_DESCENDING = "Descending"

FILEPICKER_TYPE_DOCUMENT

Describes the document type file.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_TYPE_DOCUMENT = "document"

FILEPICKER_TYPE_MUSIC

Describes the music type file.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_TYPE_MUSIC = "music"

FILEPICKER_TYPE_OTHER

Describes the other type file.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_TYPE_OTHER = "other"

FILEPICKER_TYPE_PICTURE

Describes the picture type file.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_TYPE_PICTURE = "picture"

FILEPICKER_TYPE_VIDEO

Describes the video type file.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_TYPE_VIDEO = "video"

FILEPICKER_VIEWER_MODE_DEFAULT

Describes the default view for the viewer of the FilePicker.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_VIEWER_MODE_DEFAULT = "Default"

FILEPICKER_VIEWER_MODE_GRID

Describes the grid view for the viewer of the FilePicker.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_VIEWER_MODE_GRID = "GridView"

FILEPICKER_VIEWER_MODE_LIST

Describes the list view for the viewer of the FilePicker.

Synopsis:

constant
String blackberry.invoke.card.FILEPICKER_VIEWER_MODE_LIST = "ListView"

Last modified: 2014-03-10