ab-plugin-featNow that Corona Plugins is a reality, we’re seeing a rapid deployment of new features to Corona. Last week, we blogged about the new social plugin. This week, we introduce the Address Book plugin. Right now, this is for iOS devices only, but Android development will soon be underway.

Getting Started

Like all plugins, you need to include the address book in your build.settings file:

Basic Code

The address book plugin is implemented via the native.showPopup() API, just like the social plugin. You do not need to “require” anything to use this. In your code, simply call:

The params table is the most important here — this table is mandatory and consists of options that dictate how the popup will behave. At this time, the plugin can fetch an existing contact, update an existing contact, create a new contact, or find a contact. Let’s inspect the format of this table:

  • option (string) — dictates the behavior of the contact dialog. Options are:
     ”pickContact” – pick a contact from a listing of all contacts contained in the users address book.
    “newContact” – create a new contract entry.
    “viewContact” – open an individual contact entry.
    “unknownContact” – add to a new or append to an existing contact.
  • listener — a callback function to handle the data returned from the address book. Only required for “pickContact”.

Extending the Options

Depending on the specified option from above, there are additional entries that can be specified in the options table. Let’s go through these per option:

“pickContact”

  • hideDetails (true/false) — if true, the address book display will be dismissed upon selecting a contact. If set to false, the address book will display the detail view of the contact selected.

“newContact”

  • data (table) — a table of fields to “pre-fill” the new contact form with. For example:

The list of basic data elements includes — but is not limited to — the following:

  • firstName
  • lastName
  • organization
  • homePhone
  • workPhone
  • homeEmail
  • workEmail

NOTE:  this is not an exhaustive and complete list. People may have multiple addresses (email or physical), custom phone numbers, etc.

“viewContact”

The viewContact option requires that you to pass a name query to search for. It will show the contact details for the nearest matching contact.

  • name (string) — the name of the contact to search for.
  • performDefaultAction (true/false) — if true, tapping on phone numbers will make a call; tapping on an email address will start an email to that user.
  • isEditable (true/false) — if true, you can open the record to edit it. If false, then it’s view only.
  • filter (table) — a table of strings representing which fields you want to display on the resulting view of the contact. The ordering of these is not important.

“unknownContact”

This will let you add to an existing contact.

  • performDefaultAction (true/false) — if true then tapping/touching a contacts phone number or email will perform the default iOS action (such as call the contact or show the email composition popup).
  • allowsActions (true/false) — specifies whether buttons appear to let the user perform actions such as sharing the contact, initiating a FaceTime call, or sending a text message.
  • allowsAdding (true/false) — the person’s record is only added to the address book database if allowsAdding is true and the user taps the “Add to Existing Contact” or “Create New Contact” button.
  • alternateName (string) — provides a value that is displayed instead of the first and last name.
  • message — text displayed below alternateName.
  • data — a table of fields to add/append to a contact. For example:

Callback Listener

Only “pickContact” requires a callback listener. The callback listener essentially brings back data from a “pickContact” address popup. The specified function is passed an event table that contains an event.name, event.type and an event.data table. This event.data table contains the returned values from the contact. Depending on what information is filled out for that individual contact, this table will contain that information. See the entry above that lists the potential fields that can be returned.

A very basic contact picker could be written like this:

In Summary

Accessing the user’s contacts in iOS is that easy! To get up and running as quickly as possible, you may want to check out the sample code in our GitHub repository. Additionally, please check out the documentation for the plugin.

Original article:

Tutorial: Access to iOS Contacts