Invoking apps using active text

UI controls with text can display certain strings as active text elements, similar to a hyperlink that a user can tap or press. An active text element is used to invoke an app that is designed to be an invocation target. Active text elements that are built into the BlackBerry 10 OS include email addresses, phone numbers, PINs, hashtags, and web addresses. These elements appear in emails, calendar entries, contact cards, and so on. You can add custom active text elements that invoke your app by registering string patterns and application targets with the BlackBerry 10 OS.

A custom active text element for your app is specified in the bar-descriptor.xml file of your app's project. This is done in one of two ways: through a Uniform Resource Identifier (URI) pattern or a regular expression pattern. In both cases, you must also specify your app as the invocation target. The pattern and target are registered with the BlackBerry 10 OS when the app is installed on the device.

To invoke an app from active text, the app must be available in the same space as the app where the active text appears (personal or work).

To use a URI pattern, you specify the start of a URI. This can be the scheme portion alone (for example myuri:) or it can be a longer form (for example myuri:createid). Strings in UI controls become active text elements if they start with this pattern, conform to the syntax of a URI, and an invocation filter is specified as described below.

To use a regular expression pattern, you specify a regular expression that conforms to the ICU regular expression standard. For more information on this standard, see the ICU User Guide. Strings in UI controls become active text elements if they match this pattern exactly.

Patterns are specified in the bar-descriptor.xml file using the <invoke-target> element. Here's an example app that adds both a URI pattern and a regular expression pattern:

<invoke-target id="com.mycompany.myapplication">
    <invoke-target-name>My application name</invoke-target-name>
    <invoke-target-type>application</invoke-target-type>

    <filter>
      <action>bb.action.VIEW</action>
      <mime-type>*</mime-type>
      <property var="uris" value="examplenews:"/>
    </filter>

    <invoke-target-pattern>
      <pattern-value type="regex">(?i)example\w*(server|site)</pattern-value>    
    </invoke-target-pattern>

    <invoke-target-pattern>      
      <pattern-value type="uri">examplenews:</pattern-value>    
    </invoke-target-pattern>

</invoke-target>

Attribute Description
<invoke-target> Specifies the invocation parameters of your app. For more information about <invoke-target>, see Target declaration.
<invoke-target-name> The name of your app.
<invoke-target-type> The type of your app.
<filter> Must be specified for URI pattern types only. For more information about <filter>, see Target filters.
<invoke-target-pattern> and <pattern-value> Specifies the string pattern to match. Use type="uri" for URI matching and type="regex" for regular expression matching.

To add these statements to the bar-descriptor.xml file, use the Source tab of the bar-descriptor.xml file editor in the Momentics IDE for BlackBerry.

This creates an active text element in a UI control that looks like this:

Hi Jayne,

I just added a section to our Example site . Please take a look at examplenews:today/whatsnew .

John.

For the URI pattern type, apps must be invokable with bb.action.OPEN or bb.action.VIEW.

Last modified: 2013-12-21

comments powered by Disqus