Samsung Electronics logo

Using Filters and Sorting Modes



Learning how to use filters and sorting modes allows you effectively incorporate query methods in your application:

  1. To create an attribute filter:

    The AttributeFilter filter is used to filter the search results based on an attribute value. In this example, the filter finds contacts, with the first name Chris, from the default address book.

    1. Create the filter with the AttributeFilter constructor. You can specify attribute options, such as the attribute name, match flag, and match value.

      // Use the 'firstName' attribute with a 'EXACTLY' match flag and the 'Chris' value
      
      var firstNameFilter = new webapis.AttributeFilter('name.firstName', 'EXACTLY', 'Chris');
    2. Call the find() method of the AddressBook interface to find contacts. The filter (firstNameFilter) you created is included as a parameter.

      webapis.contact.getDefaultAddressBook().find(successCB, errorCB, firstNameFilter);
  2. To create an attribute range filter:

    The AttributeRangeFilter filter is used to search for results based on a range of attribute values. In this example, the filter finds all events starting on a defined day from the calendar.

    1. Create the filter with the AttributeRangeFilter constructor. Specify the attribute, and the start and end points of the value range.

      // Use the 'startDate' attribute with a range that starts today and ends in 1 day
      // (meaning that you search for all events occurring today)
      
      var now = webapis.time.getCurrentDateTime();
      var today_begin = new webapis.TZDate(now.getFullYear(), now.getMonth(), now.getDate());
      var today_end = today_begin.addDuration(new webapis.TimeDuration(1, "DAYS"));
      var dateRangeFilter = new webapis.AttributeRangeFilter("startDate", today_begin, today_end);
    2. Call the find() method of the Calendar interface to find events. The filter (dateRangeFilter) you created is included as a parameter.

      webapis.calendar.getDefaultCalendar("EVENT").find(successCB, errorCB, dateRangeFilter);
  3. To create a composite filter:

    The CompositeFilter filter is used to search for results based on a set of filters. In this example, the filter finds contacts, whose first name contains Chris and last name is Smith, from the default address book.

    1. Create the filter with the CompositeFilter constructor. You can specify multiple sub-filters for the filter set.

      // Create an attribute filter based on the 'firstName' attribute
      var firstNameFilter = new webapis.AttributeFilter("name.firstName", "CONTAINS", "Chris");
      
      // Create an attribute filter based on the 'lastName' attribute
      var lastNameFilter = new webapis.AttributeFilter("name.lastName", "EXACTLY", "Smith");
      
      // Create a composite filter based on the intersection of these 2 filters
      // (intersection means that both filters must match for the contact to be included in the results)
      var nameCompositeFilter = new webapis.CompositeFilter("INTERSECTION", [firstNameFilter, lastNameFilter]);
    2. Call the find() method of the AddressBook interface to find matching contacts. The filter (nameCompositeFilter) you created is included as a parameter.

      webapis.contact.getDefaultAddressBook().find(successCB, errorCB, nameCompositeFilter);
  4. To use the sorting mode:

    The SortMode interface is created to sort the search results. In this example, it is used to sort contacts in the device address book in ascending order, based on their first name.

    1. Create the sort order with the SortMode() method. Specify an attribute name to sort by and an order option.

      // Use the 'firstName' attribute with a 'ASC' order
      var sortMode = new webapis.SortMode("name.firstName", "ASC");
    2. Call the find() method of the AddressBook interface to find matching contacts. In this example, the filter parameter in the find() method is defined as null, which means that the method retrieves all contacts in the address book.

      webapis.contact.getDefaultAddressBook().find(successCB, errorCB, null, sortMode);