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.

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 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 attributeSet property, which associates the metadata with the SearchableItem object.

Extends: Titanium.Proxy · Since: 5.5.0 · Platforms: iphone, ipad, macos

Properties

apiName

extended

3.2.0

3.2.0

3.2.0

9.2.0

Type: String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.

attributes

0.9

0.9

0.9

9.2.0

Type: 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.

bubbleParent

extended

3.0.0

3.0.0

3.0.0

9.2.0

Type: Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often
established by the add() method. For example, for a button added to a window, a
click event on the button would bubble up to the window. Other common parents are
table sections to their rows, table views to their sections, and scrollable views
to their views. Set this property to false to disable the bubbling to the proxy's parent.

lifecycleContainer

extended

3.6.0

Type: Titanium.UI.Window, Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks
will also be called on the proxy. Proxies that require the activity lifecycle will need this property set
to the appropriate containing Window or TabGroup.

queryString

creation only

0.9

0.9

0.9

9.2.0

Type: String

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

This parameter cannot be null.

Methods

addEventListener

extended

0.9

0.9

0.9

9.2.0

Adds the specified callback as an event listener for the named event.

Parameters:

Name	Type	Summary	Optional
name	String	Name of the event.	No
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired.	No

applyProperties

extended

3.0.0

3.0.0

3.0.0

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that
myproxy[key] = value.

Parameters:

Name	Type	Summary	Optional
props	Dictionary	A dictionary of properties to apply.	No

cancel

0.9

0.9

0.9

9.2.0

Cancels a query operation.

fireEvent

extended

0.9

0.9

0.9

9.2.0

Fires a synthesized event to any registered listeners.

Parameters:

Name	Type	Summary	Optional
name	String	Name of the event.	No
event	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.	Yes

isCancelled

0.9

0.9

0.9

9.2.0

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

Returns: Boolean — Returns `true` if the query was cancelled.

removeEventListener

extended

0.9

0.9

0.9

9.2.0

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function
in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters:

Name	Type	Summary	Optional
name	String	Name of the event.	No
callback	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to addEventListener.	No

start

0.9

0.9

0.9

9.2.0

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

Events

completed

0.9

0.9

0.9

9.2.0

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

Event Properties:

Name	Type	Summary
success	Boolean	Indicates if the operation succeeded. Returns true if download succeeded, false otherwise.
error	String	Error message, if any returned. Undefined otherwise.

founditems

0.9

0.9

0.9

9.2.0

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

Event Properties:

Name	Type	Summary
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.

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();