Contacts

v1.0.0

Contents

Installation

In order to use Ionic Enterprise Edition plugins you should make sure you're using the Ionic Enterprise Cordova CLI as the regular version can have issues with scoped plugins.

npm uninstall -g cordovanpm install -g @ionic-enterprise/cordova

Once you've installed the Ionic Enterprise Cordova CLI you can install the plugin.

ionic enterprise register --key=YOURPRODUCTKEYionic cordova plugin add @ionic-enterprise/contacts

[

](#ionic-contacts)

This plugin allows to read, write and pick contacts.

[

Usage

](#usage)

The Contacts plugin ship with a native Angular & es2015+/Typescript wrappers as well as being available on window.

// Angular
import { Contacts } from '@ionic-enterprise/contacts/ngx';
import { Contact, ContactName, ContactField  } from '@ionic-enterprise/contacts';

...

constructor(private contacts: Contacts) { }

async createContact() {
  let contact = this.contacts.create();
  contact.name = new ContactName(null, 'Smith', 'John');
  contact.phoneNumbers = [new ContactField('mobile', '6471234567')];
  contact.save().then(
    () => console.log('Contact saved!', contact),
    (error: any) => console.error('Error saving contact.', error)
  );
}

...

// ES2015+/TypeScript
import { Contacts, Contact, ContactName, ContactField } from '@ionic-enterprise/contacts';

let contact = Contacts.create();
contact.name = new ContactName(null, 'Smith', 'John');
contact.phoneNumbers = [new ContactField('mobile', '6471234567')];
contact.save().then(
  () => console.log('Contact saved!', contact),
  (error: any) => console.error('Error saving contact.', error)
);

...

// Vanilla JS
document.addEventListener('deviceready', () => {
  let contact = IonicContacts.create();
  contact.name = {familyName: 'Smith', givenName: 'John'};
  contact.phoneNumbers = {type: 'mobile', value: '6471234567'};
  contact.save().then(
    () => console.log('Contact saved!', contact),
    (error) => console.error('Error saving contact.', error)
  );
});

Index

Classes

Type aliases


Classes

Contact

Contact:

Contains information about a single contact.

constructor

new Contact(id?: undefined | string, displayName?: undefined | string, name?: ContactName, nickname?: undefined | string, phoneNumbers?: ContactField[], emails?: ContactField[], addresses?: ContactAddress[], ims?: ContactField[], organizations?: ContactOrganization[], birthday?: Date | string | null, note?: undefined | string, photos?: ContactField[], categories?: ContactField[], urls?: ContactField[]): Contact

Parameters:

Name Type
Optional id undefined | string
Optional displayName undefined | string
Optional name ContactName
Optional nickname undefined | string
Optional phoneNumbers ContactField[]
Optional emails ContactField[]
Optional addresses ContactAddress[]
Optional ims ContactField[]
Optional organizations ContactOrganization[]
Optional birthday Date | string | null
Optional note undefined | string
Optional photos ContactField[]
Optional categories ContactField[]
Optional urls ContactField[]

Returns: Contact


<Optional> addresses

● addresses: ContactAddress[] | null

An array of all the contact's addresses.


<Optional> birthday

● birthday: Date | string | null

The birthday of the contact.


<Optional> categories

● categories: ContactField[] | null

An array of all the user-defined categories associated with the contact.


<Optional> displayName

● displayName: string | null

The name of this Contact, suitable for display to end users.


<Optional> emails

● emails: ContactField[] | null

An array of all the contact's email addresses.


<Optional> id

● id: string | null

A globally unique identifier.


<Optional> ims

● ims: ContactField[] | null

An array of all the contact's IM addresses.


<Optional> name

● name: ContactName | null

An object containing all components of a persons name.


<Optional> nickname

● nickname: string | null

A casual name by which to address the contact.


<Optional> note

● note: string | null

A note about the contact.


<Optional> organizations

● organizations: ContactOrganization[] | null

An array of all the contact's organizations.


<Optional> phoneNumbers

● phoneNumbers: ContactField[] | null

An array of all the contact's phone numbers.


<Optional> photos

● photos: ContactField[] | null

An array of the contact's photos.


<Optional> rawId

● rawId: string | null

A globally unique identifier on Android.


<Optional> urls

● urls: ContactField[] | null

An array of web pages associated with the contact.


clone

clone(): Contact

Creates a deep copy of this Contact. With the contact ID set to null.

Returns: Contact copy of this Contact


display

display(allowEdit?: undefined | false | true): Promise<any>

iOS only Display a contact in the native Contact Picker UI

Parameters:

Name Type Description
Optional allowEdit undefined | false | true true display the contact and allow editing it false (default) display contact without editing

Returns: Promise<any>


remove

remove(): Promise<any>

Removes contact from device storage.

Returns: Promise<any>


save

save(): Promise<any>

Persists contact to device storage.

Returns: Promise<any>



ContactAddress

ContactAddress:

Contact address.

constructor

new ContactAddress(pref?: undefined | false | true, type?: undefined | string, formatted?: undefined | string, streetAddress?: undefined | string, locality?: undefined | string, region?: undefined | string, postalCode?: undefined | string, country?: undefined | string): ContactAddress

Parameters:

Name Type
Optional pref undefined | false | true
Optional type undefined | string
Optional formatted undefined | string
Optional streetAddress undefined | string
Optional locality undefined | string
Optional region undefined | string
Optional postalCode undefined | string
Optional country undefined | string

Returns: ContactAddress


<Optional> country

● country: string | null

The country name.


<Optional> formatted

● formatted: string | null

The full address formatted for display.


<Optional> id

● id: string | null

unique identifier, should only be set by native code


<Optional> locality

● locality: string | null

The city or locality.


<Optional> postalCode

● postalCode: string | null

The zip code or postal code.


<Optional> pref

● pref: undefined | false | true

Set to true if this ContactAddress contains the user's preferred value.


<Optional> region

● region: string | null

The state or region.


<Optional> streetAddress

● streetAddress: string | null

The full street address.


<Optional> type

● type: string | null

A string indicating what type of field this is, home for example.



ContactError

ContactError:

ContactError. An error code assigned by an implementation when an error has occurred

constructor:

constructor

new ContactError(code: number): ContactError

Parameters:

Name Type
code number

Returns: ContactError


code

● code: number

Error code


<Optional> message

● message: undefined | string

Error message


<Static> INVALID_ARGUMENT_ERROR

● INVALID_ARGUMENT_ERROR: number = 1


<Static> IO_ERROR

● IO_ERROR: number = 4


<Static> NOT_SUPPORTED_ERROR

● NOT_SUPPORTED_ERROR: number = 5


<Static> OPERATION_CANCELLED_ERROR

● OPERATION_CANCELLED_ERROR: number = 6


<Static> PENDING_OPERATION_ERROR

● PENDING_OPERATION_ERROR: number = 3


<Static> PERMISSION_DENIED_ERROR

● PERMISSION_DENIED_ERROR: number = 20


<Static> TIMEOUT_ERROR

● TIMEOUT_ERROR: number = 2


<Static> UNKNOWN_ERROR

● UNKNOWN_ERROR: number = 0

Error codes



ContactField

ContactField:

Generic contact field.

constructor

new ContactField(type?: undefined | string, value?: undefined | string, pref?: undefined | false | true): ContactField

Parameters:

Name Type
Optional type undefined | string
Optional value undefined | string
Optional pref undefined | false | true

Returns: ContactField


<Optional> id

● id: string | null

unique identifier, should only be set by native code


<Optional> pref

● pref: undefined | false | true

Set to true if this ContactField contains the user's preferred value.


<Optional> type

● type: string | null

A string that indicates what type of field this is, home for example.


<Optional> value

● value: string | null

The value of the field, such as a phone number or email address.



ContactFindOptions

ContactFindOptions:

ContactFindOptions. Search options to filter

constructor

new ContactFindOptions(filter?: undefined | string, multiple?: undefined | false | true, desiredFields?: string[], hasPhoneNumber?: undefined | false | true): ContactFindOptions

Parameters:

Name Type
Optional filter undefined | string
Optional multiple undefined | false | true
Optional desiredFields string[]
Optional hasPhoneNumber undefined | false | true

Returns: ContactFindOptions


<Optional> desiredFields

● desiredFields: string[]

Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields.


<Optional> filter

● filter: undefined | string

The search string used to find navigator.contacts.


<Optional> hasPhoneNumber

● hasPhoneNumber: undefined | false | true

(Android only): Filters the search to only return contacts with a phone number informed.


<Optional> multiple

● multiple: undefined | false | true

Determines if the find operation returns multiple navigator.contacts. Defaults to false.



ContactName

ContactName:

Contact name.

constructor

new ContactName(formatted?: undefined | string, familyName?: undefined | string, givenName?: undefined | string, middleName?: undefined | string, honorificPrefix?: undefined | string, honorificSuffix?: undefined | string): ContactName

Parameters:

Name Type
Optional formatted undefined | string
Optional familyName undefined | string
Optional givenName undefined | string
Optional middleName undefined | string
Optional honorificPrefix undefined | string
Optional honorificSuffix undefined | string

Returns: ContactName


<Optional> familyName

● familyName: string | null

The contact's family name.


<Optional> formatted

● formatted: string | null

The complete name of the contact.


<Optional> givenName

● givenName: string | null

The contact's given name.


<Optional> honorificPrefix

● honorificPrefix: string | null

The contact's prefix (example Mr. or Dr.)


<Optional> honorificSuffix

● honorificSuffix: string | null

The contact's suffix (example Esq.).


<Optional> middleName

● middleName: string | null

The contact's middle name.



ContactOrganization

ContactOrganization:

Contact organization.

constructor

new ContactOrganization(type?: undefined | string, name?: undefined | string, department?: undefined | string, title?: undefined | string, pref?: undefined | false | true): ContactOrganization

Parameters:

Name Type
Optional type undefined | string
Optional name undefined | string
Optional department undefined | string
Optional title undefined | string
Optional pref undefined | false | true

Returns: ContactOrganization


<Optional> department

● department: string | null

The department the contract works for.


<Optional> id

● id: string | null

unique identifier, should only be set by native code


<Optional> name

● name: string | null

The name of the organization.


<Optional> pref

● pref: undefined | false | true

Set to true if this ContactOrganization contains the user's preferred value.


<Optional> title

● title: string | null

The contact's title at the organization.


<Optional> type

● type: string | null

A string that indicates what type of field this is, home for example.



Contacts

Contacts:

Access and manage Contacts on the device.

create

create(properties?: any): Contact

This function creates a new contact, but it does not persist the contact to device storage. To persist the contact to device storage, invoke contact.save().

Parameters:

Name Type Description
Optional properties any an object whose properties will be examined to create a new Contact

Returns: Contact new Contact object


find

find(fields: ContactFieldType[], options?: ContactFindOptions): Promise<Contact[]>

Returns an array of Contacts matching the search criteria.

Parameters:

Name Type Description
fields ContactFieldType[] that should be searched
Optional options ContactFindOptions that can be applied to contact searching

Returns: Promise<Contact[]> a promise that resolves with the array of Contacts matching search criteria


newContactUI

newContactUI(): Promise<string>

iOS only Create a contact using the iOS Contact Picker UI

returns: a promise that resolves with the id of the created contact as param to successCallback

Returns: Promise<string>


pickContact

pickContact(): Promise<Contact>

This function picks contact from phone using contact picker UI

Returns: Promise<Contact> a promise that resolves with the selected Contact object



Type aliases

ContactFieldType

Ƭ ContactFieldType: "" | "addresses" | "birthday" | "categories" | "country" | "department" | "displayName" | "emails" | "name.familyName" | "name.formatted" | "name.givenName" | "name.honorificPrefix" | "name.honorificSuffix" | "id" | "ims" | "locality" | "name.middleName" | "name" | "nickname" | "note" | "organizations" | "phoneNumbers" | "photos" | "postalCode" | "region" | "streetAddress" | "title" | "urls"*


Other Versions