Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

RhoContact API

Provides access to a device’s phone book and contacts. For a code example, see the view and controller in the /app/Contacts folder in the System API Samples application. For other examples, refer to PIM Contacts in Rhodes Device Capabilities.

Enabling the Contacts

To use the RhoContact API, you need to enable read and write for the contacts on the device. Do this by adding that capability to the build.yml file:

capabilities:
  - pim

find

Returns the contacts in the device phone book.

Rho::RhoContact.find(argument list)

The argument list can consist of the following arguments.

:all Return a hash of hashes of all the contacts in the phonebook.
id return a hash of the properties of the contact identified by this id.

It is allowed to pass additional params hash on all platforms. Platforms that do not have the extended functionality will just skip these.

For Android and iOS, you can have the following arguments.

:first return the first contact in the list.
:count return the total number of contacts in the list.

When you use the :all, :first, or :count arguments with Android or iOS, you can also use the following optional arguments to paginate the contact list. If used with :count, the exact number of returned contacts can be determined (for example for last page).

:per_page maximum number of contacts to return.
:offset offset from the beginning of the list.
:max_results used with :count. maximum number of contacts to be returned.
:select Android only. array of string attributes to return with the object. Useful if your contacts have many attributes and your query only needs a few of them. Sample call: companylastnamelist = Phonebook.find(:all, :select => ['last_name','company_name'])
:conditions Android only. A hash of conditions.

Refer to Find Conditions for the :conditions settings.

create!

Create a new contact in the phonebook, setting its properties passed as a parameter hash. Returns the new contact as a hash.

Rho::RhoContact.create!(contact)
contact A hash containing the contact properties.

destroy

Delete this contact from the phonebook.

Rho::RhoContact.destroy(id)
id Delete the contact identified by this id

update_attributes

Find contact record in the phonebook, update record properties from the hash passed as parameter, and save updated record. Contact id passed in the hash.

Rho::RhoContact.update_attributes(contact)
contact A hash containing the contact properties to change for this contact.

Contact Properties

The contact properties are stored in a hash.

id int. The id for this contact.
first_name String. The first name for this contact.
last_name String. The last name for this contact.
mobile_number String. The mobile phone number for this contact.
business_number String. The business phone number for this contact.
email_address String. The email address for this contact. On iPhone, mapped to "work".
company_name String. The company name for this contact.

Additional Contact Properties for Android Nexus

Android uses these contact properties (stored in a hash).

display_name String. The display name for this contact.
home_number String. The home phone number for this contact.

Additional Contact Properties for iPhone

prefix String. The prefix for the name, such as "Mr."
middle_name String. The middle name for this contact.
suffix String. The suffix for this contact, such as "Jr."
nickname String. The nickname for this contact.
birthday String. The birthday for this contact, formatted as YYYY-MM-DD.
anniversary String. The anniversary for this contact, formatted as YYYY-MM-DD.
created String. The date this contact was created, formatted as YYYY-MM-DD.
updated String. The most recent date this contact was updated, formatted as YYYY-MM-DD.
company_name String. The company name for this contact.
job_title String. The job title for this contact.
assistant_name String. The name of the assistant for this contact.
assistant_number String. The phone number of the assistant for this contact.
spouse_name String. The name of the spouse for this contact.
person_note String. A note for this contact.
home_email_address String. Home email address for this contact.
other_email_address String. Other email address for this contact.
other_email_address String. Other email address for this contact.
home_page String. url of the contact's home page.
main_number pager_number home_fax work_fax Strings. Additional phone numbers for iPhone.

Additional Address Properties for iPhone

Address properties mapped to "work" Strings. "street_address_1", "city_1", "state_1", "zip_1", "country_1"
Address properties mapped to "home" Strings. "street_address_2", "city_2", "state_2", "zip_2", "country_2"
Address properties mapped to "other" Strings. "street_address_3", "city_3", "state_3", "zip_3", "country_3"

Find Conditions

The :conditions parameter, for Android platforms, is a hash of conditions. The keys of the hash are contact property selectors (condition to be applied to), and the values are the conditions.

The property selectors are: - :phone - :email

The following conditions are currently supported: - ‘not_nil’ - ‘is_nil’

A property selector has no one-to-one relation to a single contact property like mobile_phone or email_address. The selectors are mapped to a whole property group, like all phones or all emails (support for several emails may be implemented in future).

A condition like the following code will select all contacts which have at least one phone. :::ruby @count = Rho::RhoContact.find(:count, :conditions => {:phone => ‘not_nil’})

It may be useful to sort received contacts (especially if paginated). Contacts is ordered by ‘display_name’ column and then split for pages. Unfortunately, the order inside the page is lost while passing the list to ruby.

Back to Top