Discovering Search on BlackBerry 10

Native SDK Development

Does your app have a search feature? Then you should integrate with the Search app. It’s that simple.  It’s very easy, and makes your app more visible to the user (especially with the addition of Instant Action on the Q10).

TITLE_IMAGE

How?

First, make your app an Invocation target by adding something like this to your bar-descriptor.xml file:

<invoke-target id="bb.community.extendedsearchsample.search">
              <invoke-target-type>APPLICATION</invoke-target-type>
              <filter>
                     <action>bb.action.SEARCH.EXTENDED</action>
                     <mime-type>application/vnd.bb.search.criteria</mime-type>
              </filter>
       </invoke-target>

You specify the invoke-target id property, but everything else there is just a copy/paste.

Next, you need to do a bit of actual work and handle the invocation in code. When your application starts up, you want to register for the invoked signal of InvokeManager:

       _invokeManager = new InvokeManager(this);
       connect(_invokeManager, SIGNAL(invoked(const bb::system::InvokeRequest&)),
                     this, SLOT(onInvoked(const bb::system::InvokeRequest&)));

If it makes sense for you, you can also do something different at startup when the app is invoked, like load a completely different QML file.

       switch (_invokeManager->startupMode()) {
       case ApplicationStartupMode::LaunchApplication:
              // Normal launch
              break;
       case ApplicationStartupMode::InvokeApplication:
              // App was invoked.
              // This is what the search app does, but you could
              // also end up here if you have registered for other
              // invocations.

              // You may want to set a special property or load a specific UI
              break;
       case ApplicationStartupMode::InvokeViewer:
       case ApplicationStartupMode::InvokeCard:
              // Invoked other ways, only applicable if you are using the invocation
              // framework for something other than search.
              break;
       }

    QmlDocument *qml = QmlDocument::create("asset:///main.qml").parent(this);
    _root = qml->createRootObject<AbstractPane>();
    app->setScene(_root);

Your onInvoked() slot is where the real magic happens though. You get this signal when your app is invoked, whether it was just launched or already running. The InvokeRequest object you get has the action used to invoke your app (for search it’s bb.action.SEARCH.EXTENDED), as well as the search string in the data attribute. All you need to do is take that string and use it to initiate a search in your app. I’d recommend doing something like the following and setting a property in your root AbsbtractPane:

void ApplicationUI::onInvoked(const bb::system::InvokeRequest& invokeRequest) {

       if(invokeRequest.action() == "bb.action.SEARCH.EXTENDED") {
              // Begin searching in app
              _root->setProperty("searchString", QString(invokeRequest.data()));
       } else {
              // some other invocation..
       }
}

Then, in your QML file just create the property and make changing it do a search, either through the on<propertyName>Changed signal, or using property binding:

Page {
    property string searchString
    onSearchStringChanged: {
        // Show the search UI if it's not visible

        // Do the search

    }

    // This is just an example UI for you to test with, using property binding
    Container {
        TextField {
            id: searchField
            text: searchString
            hintText: "Enter search string"
            onTextChanging: {
                searchString = text;
            }
        }
        Label {
            text: "Searching for: " + searchString
        }

        Label {

            text: searchString.length > 0 ? "No '" + searchString + "' found." : ""
        }
    }
}

This is a simple example, but it’s a simple thing to do. Get the full source here. If you have any questions or comments, send them my way on Twitter: @PBernhardt

About Paul Bernhardt

I work for BlackBerry on the Developer relations team helping developers write apps in Cascades. I focus on camera, gaming and Unity mostly. My views are my own. In my free time, I'm a hardcore PC gamer and draw D&D maps for fun!

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus