# Titanium.App.iOS.SearchQuery

A search query object manages the criteria to apply when searching app content that you have previously indexed by using the Core Spotlight APIs.

Availability
5.5.0
9.2.0

# Overview

You can use this API to search multiple Titanium.App.iOS.SearchableItem objects at the same time. You can do that by using the queryString parameter that has a special syntax to filter and index several items. Please refer to the official Apple documentation (opens new window) for detailed information on how to structure your search-query to get the best possible results.

To use this feature make sure you have a compatible device running iOS 10 or later.

To create a SearchableItem object, use the Titanium.App.iOS.createSearchableItem method. Pass a dictionary of properties to the method that will help identify the item. At minimum, you must set the Titanium.App.iOS.SearchableItem.attributeSet property, which associates the metadata with the SearchableItem object.

# Examples

# Perform a simple search-query for all items that start with "Searchable" in it.

The following example demonstrates how to search a Ti.App.iOS.SearchableItem using the iOS 10 Ti.App.iOS.SearchQuery API.

# app.js

var win = Ti.UI.createWindow({
    backgroundColor: "#fff"
});
var btn = Ti.UI.createButton({
    title: "Start search-query"
});

var searchItems = [];
var itemAttr = Ti.App.iOS.createSearchableItemAttributeSet({
    itemContentType: Ti.App.iOS.UTTYPE_IMAGE,
    title: "Titanium Core Spotlight Tutorial"
});

itemAttr.contentDescription = "Tech Example \nOn: " + String.formatDate(new Date(), "short");
itemAttr.keywords = ["Mobile", "Appcelerator", "Titanium"];
itemAttr.displayName = "Hello world";

var item = Ti.App.iOS.createSearchableItem({
    uniqueIdentifier: "my-id",
    domainIdentifier: "com.mydomain",
    attributeSet: itemAttr
});
searchItems.push(item);

var indexer = Ti.App.iOS.createSearchableIndex();

indexer.addToDefaultSearchableIndex(searchItems, function(e) {
    if (e.success) {
        Ti.API.info("Press the home button and now search for your keywords");
    } else {
        alert("Searchable index could not be created: " + JSON.stringify(e.error));
    }
});

btn.addEventListener("click", function() {
    // An array of found Ti.App.iOS.SearchableItem's
    var allItems = [];

    // The search-query
    var searchQuery = Ti.App.iOS.createSearchQuery({
        queryString: 'title == "Titanium*"',
        attributes: ["title", "displayName", "keywords", "contentType"]
    });

    // The event to be called when a new batch of items is found
    searchQuery.addEventListener("founditems", function(e) {
        for (var i = 0; i < e.items.length; i++) {
            allItems.push(e.items[i]);
        }
    });

    // The event to be called when the search-query completes
    searchQuery.addEventListener("completed", function(e) {
        if (!e.success) {
            alert(e.error);
        }

        for (var i = 0; i < allItems.length; i++) {
            var attributeSet = allItems[i].attributeSet
            var foundTitle = attributeSet.title
            var foundDisplayName = attributeSet.displayName

            Ti.API.info("title: " + foundTitle + ", displayName: " + foundDisplayName);
        }
    });

    // Start the search-query (or use searchQuery.cancel()) to abort it
    searchQuery.start();
});

win.add(btn);
win.open();

# Properties

# attributes

Availability
5.5.0
9.2.0
attributes :Array<String>

An array of strings that represent the attributes of indexed items.

Each string corresponds to a property name that can be set for an item. For a list of possible properties, see the Titanium.App.iOS.SearchableItemAttributeSet API. Passing null for this parameter means that the query does not use attributes to find matching items.


# queryString CREATION ONLY

Availability
5.5.0
9.2.0
queryString :String

A formatted string that defines the matching criteria to apply to indexed items.

This parameter cannot be null.

# Methods

# cancel

Availability
5.5.0
9.2.0
cancel() void

Cancels a query operation.

Returns

Type
void

# isCancelled

Availability
5.5.0
9.2.0
isCancelled() Boolean

A Boolean value that indicates if the query has been cancelled (true) or not (false).

Returns

Returns true if the query was cancelled.

Type
Boolean

# start

Availability
5.5.0
9.2.0
start() void

Asynchronously queries the index for items that match the query object's specifications.

Returns

Type
void

# Events

# founditems

Availability
5.5.0
9.2.0

Fired when the query finds a new batch of matching items.

Properties

Name Type Description
items Array<Titanium.App.iOS.SearchableItem>

An array of indexed items that match the specified query.

foundItemsCount Number

The number of items that are currently fetched.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.


# completed

Availability
5.5.0
9.2.0

Fired when the query completes to inform you about it's success. To receive items, use the founditems event.

Properties

Name Type Description
success Boolean

Indicates if the operation succeeded. Returns true if download succeeded, false otherwise.

error String

Error message, if any returned. Undefined otherwise.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.