onymos-logo

onymosContacts.getList

To obtain a filtered list of Contacts from the Device, we call the Onymos Contacts Get List function.

This function returns only 100 (default) Contacts, for better performance. You can use the loadNextSet function repeatedly to obtain subsequent set of Contacts, as the user scrolls down in a page to view more contacts.

You can implement your entire Contacts UI functionality, using just this and the loadNextSet functions.

OnymosContacts.getList(
callId,
(listOfContactsArray) => {
/* ------
listOfContactsArray = [{
// Array of Contacts
// Fields as requested in options.displayFields
}];
------ */
},
(error) => {
console.log(error);
},
options
);
callId

String

To identify each call to select Contacts. In most cases, only one invocation will be required, and so use ‘1’. A special case example is, if your app has ‘Friends using your app’, ‘Friends not using your app’ lists, with separate actions for each list, use callId of ‘1’, and ‘2’.

options
searchField

Constant

Defines whether the Contacts have to be filtered on Given name (First name) or Family name (Last name), using the ‘filter’ string.
OnymosContactsConstants.SearchField.givenName filters on Given name.

OnymosContactsConstants.SearchField.familyName filters on Family name.

filter

String

Filter string is applied either on Given name (First name), or Family name (Last name), as set in the SearchField, and matching results are returned. Those names that ‘BEGIN WITH’ the filter string are returned. This is different behavior, but very practical, compared to other search functions on Contacts.

hasPhoneNumber

Boolean

Default: false.
When set to true, only those Contacts that have a Phone number are returned.

displayFields

Constants Array

An array of fields that you want this function to fetch for each Contact returned.
OnymosContactsConstants.DisplayFields.<fieldName>
Field Names List:
addresses, birthday, categories, country, department, displayName, emails, familyName, formatted, givenName, honorificPrefix, honorificSuffix, id, ims, locality, middleName, name, nickname, note, organizations, phoneNumbers, photos, postalCode, region, streetAddress, title, urls

Note: The fewer Contacts requested, the faster the performance, particularly on Devices with 1000s of Contacts.

numberOfRecords

Integer

Default: 100
The number of Contacts you want returned in this function, as well as in the loadNextSet function.

Note: The fewer Contacts requested, the faster the performance.

Usage Example:

{
filter: ‘Jo’,
hasPhoneNumber: true,
searchField: OnymosContactsConstants.SearchField.givenName,
displayFields: [
OnymosContactsConstants.DisplayFields.name,
OnymosContactsConstants.DisplayFields.nickname,
OnymosContactsConstants.DisplayFields.phoneNumbers,
OnymosContactsConstants.DisplayFields.emails,
OnymosContactsConstants.DisplayFields.addresses,
OnymosContactsConstants.DisplayFields.note
],
numberOfRecords: 200
}

onymosContacts.loadNextSet

After a successful invocation of getList function, you can call the loadNextSet function, to obtain the next set of 100 (default) Contacts matching the same critera as set in getList function.

This function returns an array of 0 size, if there are no more Contacts available to load.

This function is usually called in response to a scroll-down event. When the user scrolls below a certain number of records, this function is called and the next set of Contacts are appended to the display.

OnymosContacts.loadNextSet(
callId,
(nextSetOfContactsArray) => {
/* ------
nextSetOfContactsArray = [{
// Array of Contacts
// Fields as requested in options.displayFields with the getList function.
}];
------ */
},
(error) => {
console.log(error);
}
);
callId

String

Use the same callId used during Onymos Contacts getList function.

onymosContacts.loadSpecificSet

After a successful invocation of getList function, you can call the loadSpecificSet function, to obtain a specific set of Contacts, from a start position to end position in the list, matching the same critera as set in getList function.

This function is usually called in response to a scroll-up event, to load back a specific set of Contacts that were removed to save on memory usage.

As an example, when a user with a matched list of 600 Contacts, is viewing Contacts from 300 to 400, Contacts from 0 to 299 can be removed. When the user scrolls up, you can use this function to load contacts from 200 to 299 and add it to the front of the display list.

OnymosContacts.loadSpecificSet(
callId,
start,
end,
(specificSetOfContactsArray) => {
/* ------
specificSetOfContactsArray = [{
// Array of Contacts
// Fields as requested in options.displayFields with the getList function.
}];
------ */
},
(error) => {
console.log(error);
}
);
callId

String

Use the same callId used during Onymos Contacts getList function.

start

Integer

The starting position in the matched Contacts you want returned.
Note: Use 0 for the first position.

end

Integer

The ending position in the matched Contacts you want returned.
Note: Contacts up to end – 1 position are returned.
start = 0, end = 100, returns Contacts from 0th position to 99th position.

Think differently about app development

Download our free white paper today to learn how Onymos Features can maximize the value of your developer resources — and shave weeks or months off your development timeline.

Get your free white paper

Overlay