buildfire.device.contacts

This feature allows the app to access and to get devices contacts.

note

This feature works only on devices; so it will return an error if it was triggered outside devices

Requirements

plugin.json

In plugin.json add Contacts in your features array "features" : [{"name" : "Contacts"}]

Methods

showDialog()

buildfire.device.contacts.showDialog(options, callback)

This function allows you to select one contact, where it shows the contacts in the device via native UI and you can select one of them. It may also ask the user for permission to access the device's contacts if it hasn't previously.

buildfire.device.contacts.showDialog({}, (err, contact) => {
  if(err) return console.error(err);
  console.log("The Selected Contact", contact);
});

callback(err, data)

Callback function after selecting a contact

Name	Type	Description
err	string	Error string, null when operation is successful
data	object	The selected contact

data

Name	Type	Description
name	string	The name of the contact
emails	[object]	Array of the contact's emails, example "emails": [{"value":<string>,"pref":<bool>,"id":<number>,"type":<string>}
photos	[object]	Array of the contact's photos, example "photos": [{"value":<string>,"pref":<bool>,"type":<string>
phoneNumbers	[object]	Array of the contact's phone numbers, example "phoneNumbers": [{"value":<string>,"pref":<bool>,"id":<number>,"type":<string>}

note

pref and type in (emails, photos and phoneNumbers) are widely supported but make sure to check nullability (or being undefined) for both of them

Example of the received data

{
  "name":"John Appleseed",
  "emails": [
    {
      "value":"John-Appleseed@mac.com","pref":false,"id":0,"type":"work"
    }
  ],
  "photos": [
    {
      "value":"/Users/buildfire/Library/Developer/CoreSimulator/Devices/2384C1C9-2898-4633-AB6B-E8A76DDC0B1D/data/Containers/Data/Application/
       099B01C2-290E-446B-A0A2-D760FB78AF14/tmp/contact_photo_3","type":"url","pref":"false"
    }
  ],
  "phoneNumbers": [
    {
      "value":"888-555-5512","pref":false,"id":0,"type":"mobile"
    },
    {
      "value":"888-555-1212","pref":false,"id":1,"type":"home"
    }
  ]
}

---

search()

buildfire.device.contacts.search(options, callback)

This function allows you to select multiple contacts, where you will get all the contacts (in a drawer) from the device and you can select from them. It may also ask the user for permission to access the device's contacts if it hasn't previously.

buildfire.device.contacts.search({}, (err, contacts) => {
  if(err) return console.error(err);
    console.log("The Selected Contacts", contacts);
});

options

Name	Type	Required	Description	Default
header	string	no	Text or HTML to be rendered as the drawer's header
content	string	no	Text or HTML to be rendered in the drawer's body
exclude	object	no	Rule to exclude contacts in search results
drawerButtonText	string	no	Text of the button	'Import'
drawerButtonType	string	no	Type of the button (primary, success, info, danger, warning, default)	'success'

options.exclude

Name	Type	Required	Description	Default
terms	[string]	no	Array of string terms to search for in contacts to be excluded. Terms will be matched against contact name, emails and phone numbers
match	string	no	Specifies whether to exclude a contact when any of the contact's info contains a term contains or when any of the contact's info exactly matches a term exact	'exact'

callback(err, data)

Callback function after selecting contacts

Name	Type	Description
err	string	Error string, null when operation is successful
data	[object]	Array of the selected contacts

data

Name	Type	Description
name	string	The name of the contact
emails	[object]	Array of the contact's emails, example "emails": [{"value":<string>,"pref":<bool>,"id":<number>,"type":<string>}
photos	[object]	Array of the contact's photos, example "photos": [{"value":<string>,"pref":<bool>,"type":<string>
phoneNumbers	[object]	Array of the contact's phone numbers, example "phoneNumbers": [{"value":<string>,"pref":<bool>,"id":<number>,"type":<string>}

note

pref and type in (emails, photos and phoneNumbers) are widely supported but make sure to check nullability (or being undefined) for both of them

Example of the received data

{
  "name":"John Appleseed",
  "emails": [
    {
      "value":"John-Appleseed@mac.com","pref":false,"id":0,"type":"work"
    }
  ],
  "photos": [
    {
      "value":"/Users/buildfire/Library/Developer/CoreSimulator/Devices/2384C1C9-2898-4633-AB6B-E8A76DDC0B1D/data/Containers/Data/Application/
       099B01C2-290E-446B-A0A2-D760FB78AF14/tmp/contact_photo_3","type":"url","pref":"false"
    }
  ],
  "phoneNumbers": [
    {
      "value":"888-555-5512","pref":false,"id":0,"type":"mobile"
    },
    {
      "value":"888-555-1212","pref":false,"id":1,"type":"home"
    }
  ]
}

More Examples

buildfire.device.contacts.search(
  {
    header: "Contacts", 
    content: "Select Contacts", 
    drawerButtonText: "Import Contacts", 
    drawerButtonType: 'primary'
  }, 
  (err, contacts) => {
  if(err) return console.error(err);
  console.log("The Selected Contacts", contacts);
});