<rim:invoke-target>

Syntax:

<rim:invoke-target id="string">
    <type>[ APPLICATION | VIEWER ]</type>
    <filter>
        <action>string</action>
        <mime-type>mime_type</mime-type>
        <property var=["exts" | "uris"] value="string" />
    </filter>
</rim:invoke-target>

Description:

You can use the <rim:invoke-target> element to register your BlackBerry WebWorks application as a handler for invocation events. In BlackBerry 10 OS, the invocation framework provides the ability by which a client process can send a message to a target process so it can perform a certain action.

If you register your application with the invocation framework, your application can be invoked through:
  • Bound invocation: The target is invoked by using an identifier.
  • Unbound invocation: The target is invoked without specifying a target.
  • Bound and unbound invocation: The target is invoked by using an identifier and other attributes.

All invocations must specify an action that the target must perform as well as data to be acted upon. The data can be specified by using a combination of MIME types, URIs, and file extensions.

You must include the following namespace declaration in the parent <widget> element to use the <rim:invoke-target> element:

xmlns:rim="http://www.blackberry.com/ns/widgets">

Occurrences:

Zero or more.

Parent elements:

<platform>

Child elements:

Name Occurrences

<rim:filter>

zero or more

<rim:type>

one

Content:

None.

Attributes:

You can define the following attributes for this element:

Attribute Description
rim:id

Required. Specifies a globally unique name. This name is verified when you sign the application. It's recommended that you use the reverse-DNS naming convention.

Example: com.ea.needforspeed.target

Example:

Registering bound and unbound invocations

<widget xmlns:rim="http://www.blackberry.com/ns/widgets">
.
.
.
    <platform name="blackberry10">
        <rim:invoke-target id="com.domain.subdomain.appname.app">
            <type>APPLICATION</type>
            <filter>
                <action>bb.action.OPEN</action>
                <action>bb.action.SET</action>
                <mime-type>text/*</mime-type>
                <property var="exts" value="bmp,css,html,js" />
                <property var="uris" value="data://local,file://" />
            </filter>
        </rim:invoke-target>
    </platform>
</widget>

Registering multiple filters against an invocation

<widget xmlns:rim="http://www.blackberry.com/ns/widgets">
.
.
.
    <platform name="blackberry10">
        <rim:invoke-target id="com.domain.subdomain.appname.app">
            <type>APPLICATION</type>
            <filter>
                <action>bb.action.OPEN</action>
                <mime-type>application/*</mime-type>
                <mime-type>text/*</mime-type>
                <mime-type>audio/*</mime-type>
                <mime-type>image/*</mime-type>
                <mime-type>message/*</mime-type>
                <mime-type>video/*</mime-type>
            </filter>
            <filter>
                <action>bb.action.VIEW</action>
                <mime-type>text/*</mime-type>
            </filter>
            <filter>
                <action>bb.action.SET</action>
                <mime-type>image/*</mime-type>
                <property var="exts" value="bmp,png,jpg,gif" />
            </filter>
        </rim:invoke-target>
    </plaftorm>    
</widget>

Registering multiple targets against an invocation type

<widget xmlns:rim="http://www.blackberry.com/ns/widgets">
.
.
.
    <platform name="blackberry10">
        <rim:invoke-target id="com.domain.subdomain.appname.app">
            <type>APPLICATION</type>
            <filter>
                <action>bb.action.OPEN</action>
                <mime-type>image/*</mime-type>
                <mime-type>text/*</mime-type>
                <mime-type>video/*</mime-type>
            </filter>
        </rim:invoke-target>
        <rim:invoke-target id="com.domain.subdomain.appname.view">
            <type>VIEWER</type>
            <filter>
                <action>bb.action.VIEW</action>
                <mime-type>image/*</mime-type>
                <mime-type>text/*</mime-type>
                <mime-type>video/*</mime-type>
            </filter>
        </rim:invoke-target>
    </platform>
</widget>

Code sample: Parsing invoke parameters

When you set the <content> element's rim:allowInvokeParams attribute to a value of true, the start up parameters for the application are available to the start page as a query string. You can parse the query string using JavaScript.

function parseQueryString() {        

    // Create result container
    var queryParamResult;
    
    // Start at 1 to skip the leading '?'
    var query = window.location.search.substring(1);
    
    // Split the string on key-value pairs
    var params = query.split('&');
    
    // Loop through the pairs
    for ( var i = 0 ; i < params.length ; i++ ) {
        // Locate the '='
        var position = params[i].indexOf('=');
        if ( position > 0 ) {
            
            // Text before the '=' is the key
            var key = params[i].substring( 0, position );
            
            // Text after the '=' is the value
            var value = params[i].substring( position + 1 );
            
            // Add to result container
            queryParamResult[key] = value;
        }
    }
    
    return queryParamResult;
}

Last modified: 2014-10-09



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus