Invoking apps using active text

UI controls with text can display certain strings as active text that a user can tap or press, similar to a hyperlink. 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. The following table outlines the standard patterns for these built-in active text elements:

Pattern Example Limitations
Mailing address 450 March Rd. Ottawa, Ontario Canada, US, UK, Singapore, and Australia only
Email address user01@example.com None
Telephone number (519) 555-0100 Limited to Smart Dialing country code (which defaults to the SIM country code)
Device PIN 12G34H56 None
SMS URI sms:5195550100 None
Hashtag #<hashtag> None
Twitter username @<username> None
URL http://www.blackberry.com Supports http:// and https:// (The scheme must be present)

The BlackBerry 10 OS is designed to recognize the standard patterns listed above automatically, so you don't need any extra code in your app.

You can also create custom active text elements for your own applications. 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-pattern> 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> The invocation parameters of your app. For more information about <invoke-target>, see Target declaration.
<invoke-target-name> Name of your app
<invoke-target-type> Type of your app
<filter> The criteria for this application to be considered for unbound invocations or invocation queries. Must be specified for URI pattern types only. For the URI pattern type, apps must be invokable with bb.action.OPEN or bb.action.VIEW. For more information about <filter>, see Target filters.
<invoke-target-pattern> and <pattern-value> 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.

Last modified: 2014-02-18

comments powered by Disqus