Invoked

The Invoked object allows the application to be invoked by other applications.

Installation:

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

webworks plugin add com.blackberry.invoked
Functions:
void cardRequestClosure()
void cardStartPeek()
Events:
void invoked
void onCardClosed

cardRequestClosure()

As a Card, request the navigator to close itself.

Synopsis:

void blackberry.invoked.cardRequestClosure(request)

Parameters:

request {Object}

Object literal that specifies reason, type and response data of the closure request.

reason {String}

The reason that identifies application level description of why the card was closed.

type {String}

MIME type of data to be returned. It's mandatory if data is returned.

data {String}

The data that will be returned to the parent.

Example:

<script type="text/javascript">

    function requestClosure() {
        blackberry.invoked.cardRequestClosure({
            reason: "ItemSelected",
            type: "application/contact",
            data: '{"name":"......"}'
        });
    }

</script>
            

cardStartPeek()

As a Card, request the navigator to perform a peek on the deck.

Synopsis:

void blackberry.invoked.cardStartPeek(peekType)

Parameters:

peekType {String}

Describes the type of peek to perform as a peek to the content of the parent or a peek to the content of the root. The value should be either "content" or "root".

Example:

<script type="text/javascript">

    function peekParent() {
        // Request the navigator to perform a peek to the content of the parent
        document.addEventListener('touchstart', function(event) {
            blackberry.invoked.cardStartPeek("content");
        }, false);
    }

</script>
            

invoked

This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function. The invoked event is triggered by the system when the application is invoked by another application.

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the invoked event.

info {Object}

An object the pertinent information.

source {String}

Identifier of invocation target (as stated in its BAR manifest) to which the receiver can send results. Omitting the source attribute implies that the sender does NOT support results.

target {String}

Identifier of target (as stated in its BAR manifest) to which invocation should be delivered. If the target is supplied then brokering is bypassed and attempt is made to invoke the specified target.

action {String}

Identifier of action to be performed by target. Omitting action implies brokering should apply to any action supported for the specified type or that the target should infer the action.

type {String}

MIME type of data to be acted on. If the mime type is not specified then Invocation Framework would attempt to infer the mime type from the given URI. If the mime type can not 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 the data://local URI indicating that the invocation data is provided in-band in the data field of the invocation message.

data {String}

Data passed to target. Omitting the data implies that the action-type are sufficient to carry out the invocation. Note that target invocation allows passing arbitrary binary data that will be encoded into Base64 encoded string.

Example:

<script type="text/javascript">

    function onInvoked(onInvokedInfo) {
       if(onInvokedInfo.source) {
           console.log("Source: " + onInvokedInfo.source);
       }
       if(onInvokedInfo.target) {
           console.log("Target(me): " + onInvokedInfo.target);
       }
       if(onInvokedInfo.action) {
           console.log("Action: " + onInvokedInfo.action);
       }
       if(onInvokedInfo.data) {
           console.log("Data: " + onInvokedInfo.data);
           //the data comes in as a base64 string you can convert it using atob(...)
           //note that atob will fail if you are being passed unicode strings
           console.log("Data: " + atob(onInvokedInfo.data));
       }
    }

    document.addEventListener("invoked", onInvoked);

</script>
            

onCardClosed

This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function. As a Card, the onCardClosed event is fired by the navigator to it to indicate that it should clean-up its state and wait for invocation as it is pooled. When a card receives a cardClosed event it should assume that its child card is also closed (if one exists). When a card is dismissed by the Parent or navigator the reason value is "closed".

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the onCardClosed event.

request {Object}

An object that includes any response data sent by the card (if the card requested closure).

reason {String}

Describes application level description of why the card was closed. In the case that the close was due to a navigation Navigator will insert the value "navigation".

type {String}

Describes the type and encoding of the value in the data attributes.

data {String}

Describes the data that will be returned to the parent.

Example:

<script type="text/javascript">

    function onCardClosedHandler(request) {
           // If it was closed by the navigator, do the clean-up
              if (request.reason == "navigation") {
                         cleanup();
                            }
    }

    document.addEventListener("onCardClosed", onCardClosedHandler);

</script>
            

Last modified: 2014-03-10