Card

The Card object contains methods that invoke cards.


Learning Resources:

Sample - Invoking cards Sample that demonstrates how to use the BlackBerry Invoke Cards API [BlackBerry on GitHub].
Sample - Invoking cards as Share Targets Sample that demonstrates how to use the BlackBerry Invoke Cards API [BlackBerry on GitHub].

Supported Platform(s)

- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.invoke.card.invokeCalendarComposer           Y 
blackberry.invoke.card.invokeCalendarPicker           Y 
blackberry.invoke.card.invokeCamera           Y 
blackberry.invoke.card.invokeEmailComposer           Y 
blackberry.invoke.card.invokeFilePicker           Y 
blackberry.invoke.card.invokeIcsViewer           Y 
blackberry.invoke.card.invokeMediaPlayer           Y 
blackberry.invoke.card.invokeTargetPicker           Y 
CAMERA_MODE_PHOTO           Y 
CAMERA_MODE_VIDEO           Y 
CAMERA_MODE_FULL           Y 
FILEPICKER_MODE_PICKER           Y 
FILEPICKER_MODE_SAVER           Y 
FILEPICKER_MODE_PICKER_MULTIPLE           Y 
FILEPICKER_MODE_SAVER_MULTIPLE           Y 
FILEPICKER_VIEWER_MODE_LIST           Y 
FILEPICKER_VIEWER_MODE_GRID           Y 
FILEPICKER_VIEWER_MODE_DEFAULT           Y 
FILEPICKER_SORT_BY_NAME           Y 
FILEPICKER_SORT_BY_DATE           Y 
FILEPICKER_SORT_BY_SUFFIX           Y 
FILEPICKER_SORT_BY_SIZE           Y 
FILEPICKER_SORT_ORDER_ASCENDING           Y 
FILEPICKER_SORT_ORDER_DESCENDING           Y 
FILEPICKER_TYPE_PICTURE           Y 
FILEPICKER_TYPE_DOCUMENT           Y 
FILEPICKER_TYPE_MUSIC           Y 
FILEPICKER_TYPE_VIDEO           Y 
FILEPICKER_TYPE_OTHER           Y 

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.invoke.card" />           Y 

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.


Functions

static void blackberry.invoke.card.invokeCalendarComposer (options : blackberry.invoke.card.CalendarComposerOptions, onDone: function([data: String]), onCancel: function([reason: String]), onInvoke: function([error: String]))


Invokes calendar event composer card


Supported Platforms
 - BlackBerry 10


Parameters
options An object of type blackberry.invoke.card.CalendarComposerOptions which describes all options available to the event composer.
onDone The callback function that will be triggered when the user finished with the event composer.

data: The data string back from the event composer.
onCancel The callback function that will be triggered if the user cancel the event composer.

reason: A String that describes the reason the event composer was cancelled.
onInvoke The callback function that will be triggered when the event composer is invoked.

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

Code Example:
< script="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>

static void blackberry.invoke.card.invokeCalendarPicker (options : blackberry.invoke.card.CalendarPickerOptions, onDone: function([data: String]), onCancel: function([reason: String]), onInvoke: function([error: String]))

Warning

Filepaths using the local:/// protocol are not supported for this card.


Invokes calendar event picker card.


Supported Platforms
 - BlackBerry 10


Parameters
options An object of type blackberry.invoke.card.CalendarPickerOptions which describes all options available to the event picker.
onDone The callback function that will be triggered when the user finished with the event picker.

data: The data string back from the event picker.
onCancel The callback function that will be triggered if the user cancel the event picker.

reason: A String that describes the reason the event picker was cancelled.
onInvoke The callback function that will be triggered when the event picker is invoked.

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

Code Example:
< script="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>

static void blackberry.invoke.card.invokeCamera (mode : String, onSave: function([path: String]), onCancel: function([reason: String]), onInvoke: function([error: String]))


Invokes the Camera Card.


Supported Platforms
 - BlackBerry 10


Parameters
mode A string to specify the photo video or full mode.
onSave The callback function that will be triggered if the user saves a picture or video.

path: A String that describes the path of the file saved.
onCancel The callback function that will be triggered if the user does not save and simply quits the camera.

reason: A String that describes the reason the camera was cancelled.
onInvoke The callback function that will be triggered when the camera is invoked.

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

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

static void blackberry.invoke.card.invokeEmailComposer (options : blackberry.invoke.card.EmailComposerOptions, onDone: function([data: String]), onCancel: function([reason: String]), onInvoke: function([error: String]))

Warning

Filepaths using the local:/// prototcol are supported for this card.


Invokes email composer card.


Supported Platforms
 - BlackBerry 10


Parameters
options An object of type blackberry.invoke.card.EmailComposerOptions which describes all options available to the email composer.
onDone The callback function that will be triggered when the user finished with the email composer.

data: The data string back from the email composer.
onCancel The callback function that will be triggered if the user cancel the email composer.

reason: A String that describes the reason the email composer was cancelled.
onInvoke The callback function that will be triggered when the email composer is invoked.

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

Code Example:
< script="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>

static void blackberry.invoke.card.invokeFilePicker (options : blackberry.invoke.card.FilePickerOptions, onDone: function([pathArray: String]), onCancel: function([reason: String]), onInvoke: function([error: String]))


Invokes the FilePicker Card.


Supported Platforms
 - BlackBerry 10


Parameters
options An object to type blackberry.invoke.card.FilePickerOptions describe all the options available for FilePicker.
onDone The callback function that will be triggered if the user selects file(s) or folder(s).

pathArray: An Array that describes the path of each of the files saved.
onCancel The callback function that will be triggered if the user does not select file(s) or folder(s) and simply cancels.

reason: A String that describes the reason the FilePicker was cancelled.
onInvoke The callback function that will be triggered when the camera is invoked.

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

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

static void blackberry.invoke.card.invokeIcsViewer (options : blackberry.invoke.card.IcsViewerOptions, onDone: function([data: String]), onCancel: function([reason: String]), onInvoke: function([error: String]))


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


Supported Platforms
 - BlackBerry 10


Parameters
options An object to type blackberry.invoke.card.IcsViewerOptions describes all the options available for IcsViewer.
onDone The callback function that will be triggered when the event is added to a calendar.

data: A data string might be an empty or to contain some information.
onCancel The callback function that will be triggered when the card invocation has been cancelled.

reason: A string that describes the reason the IcsViewer was cancelled.
onInvoke The callback function that will be triggered when the IcsViewer card is invoked.

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

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

static void blackberry.invoke.card.invokeMediaPlayer (options : blackberry.invoke.card.MediaPlayerOptions, onDone: function([data: String]), onCancel: function([reason: String]), onInvoke: function([error: String]))


Invokes the MediaPlayer Card.


Supported Platforms
 - BlackBerry 10


Parameters
options An object to type blackberry.invoke.card.MediaPlayerOptions describe all the options available for meida player.
onDone The callback function that will be triggered when the user finished with the media player.

data: The data string back from the media player.
onCancel The callback function that will be triggered if the user cancel the media player.

reason: A String that describes the reason the MediaPlayer was cancelled.
onInvoke The callback function that will be triggered when the media player is invoked.

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

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

static void blackberry.invoke.card.invokeTargetPicker (request : Object, title : String, onSuccess: function(), onError: function())


Invokes the Target Picker Card.


Supported Platforms
 - BlackBerry 10


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

action: The action to be performed by the target.
mime: 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: 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: 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 The title string that should appear at the top of the target picker card.
onSuccess a callback that is called on successfull invocation of a target.
onError a callback function that will be triggered on error during the invocation process.

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

Constants

static String CAMERA_MODE_PHOTO


Describes the photo mode for camera.


Supported Platforms
 - BlackBerry 10

static String CAMERA_MODE_VIDEO


Describes the video mode for camera.


Supported Platforms
 - BlackBerry 10

static String CAMERA_MODE_FULL


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


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_MODE_PICKER


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


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_MODE_SAVER


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


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_MODE_PICKER_MULTIPLE


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


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_MODE_SAVER_MULTIPLE


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


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_VIEWER_MODE_LIST


Describes the list view for the viewer of the FilePicker.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_VIEWER_MODE_GRID


Describes the grid view for the viewer of the FilePicker.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_VIEWER_MODE_DEFAULT


Describes the default view for the viewer of the FilePicker.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_SORT_BY_NAME


Describes the sort by field name.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_SORT_BY_DATE


Describes the sort by field date.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_SORT_BY_SUFFIX


Describes the sort by field suffix.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_SORT_BY_SIZE


Describes the sort by field date.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_SORT_ORDER_ASCENDING


Describes the sort order of ascending.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_SORT_ORDER_DESCENDING


Describes the sort order of descending.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_TYPE_PICTURE


Describes the picture type file.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_TYPE_DOCUMENT


Describes the picture type document.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_TYPE_MUSIC


Describes the picture type music.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_TYPE_VIDEO


Describes the picture type video.


Supported Platforms
 - BlackBerry 10

static String FILEPICKER_TYPE_OTHER


Describes the picture type other.


Supported Platforms
 - BlackBerry 10

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:04 GMT-0500 (EST)