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 email messages, 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 4000 Innovation Drive, Kanata, Ontario Canada, US, UK, Singapore, and Australia only
Email address user01@example.com None
Phone 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 apps. 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: 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.

On devices that use BlackBerry Balance, the app with the active text and the app being invoked must be in the same space (personal or work).

To use a URI pattern, you specify the start of a URI. You can specify the scheme portion alone (for example, myuri:) or you can specify 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 that shows an invocation request that contains both a URI pattern and 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>

The name of your app.

<invoke-target-type>

The type of your app.

<filter>

Describes the criteria for this app 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, in the bar-descriptor.xml file editor in the Momentics IDE for BlackBerry, use the Source tab.

This example 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-11-17



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

comments powered by Disqus