Managing contacts

Using the JavaScipt API of the Simplifier Mobile Client you can manage your contacts in your business applications. There are methods to create, read, delete and edit contacts.

Reading contacts

There are two ways reading contacts. The first way is to requests all existing contacts. The second way is to pick a single contact from a list of contacts.

Requesting a list of contacts

To request a list of contacts you can use the function window.Contacts.find which requires a success callback, an error callback and an option object which describes which contact fields shall be filled. The success parameter is an Array of Contacts without the filtered fields defined by the option object.

window.ContactsX.find(fnSuccess, fnError, oContactOptions)

Example:

window.ContactsX.find(
   function (aContacts) {
      console.log(aContacts);
   },
   function (oError) {
      console.error(oError);
   },
   {
      fields: {
         displayName:true, //default: true
         firstName:true, //default: true
         middleName:true, //default: true
         familyName:true, //default: true
         phoneNumbers:true,
         emails:false,
         addresses:false
      }
   }
);

Picking a single contact

The usage of the function window.ContactsX.pick launches a Contact Picker to select a single contact. The functions requires a success callback and an error callback. The success parameter has the datatype Contact and contains all fields.

window.ContactsX.pick(fnSuccess, fnError)

Example:

window.ContactsX.pick(
   function (oSuccess) {
     console.log(oSuccess);
   },
   function (oError) {
      console.error(oError);
   }
);

Creating and editing a contact

The method window.ContactsX.save allows to create and edit contacts. This method requires a Contact object, a success callback and an error callback as parameters. The success callback receives the saved Contact object.

window.ContactsX.save(oContact, fnError, oContactOptions)

Creating a new contact

To create a new contact the Contact object must not contain the field id.

Example:

window.ContactsX.save(
   {
      firstName: "John",
      familyName: "Doe",
      phoneNumbers: [{
         type: "mobile",
         value: "112"
      }]
   },
   function (oContact) {
      console.log(oContact);
   }, 
   function (oError) {
      console.error(oError);
   }
);

Editing an existing contact

Updating a contact works just like creating one. The important point here is to include the id field and all other fields of the contact.

Example:

window.ContactsX.save(
   {
      id: "877-568-ABC",
      firstName: "John",
      familyName: "Doe",
      phoneNumbers: [{
         type: "mobile",
         value: "110112"
      }]
   },
   function (oContact) {
      console.log(oContact);
   }, 
   function (oError) {
      console.error(oError);
   }
);

Deleting a contact

The method window.ContactsX.delete allows to delete a contact. This method requires a id of an existing Contact, a success callback and an error callback as parameters.

window.ContactsX.delete(sContactId, fnSuccess, fnError)

Example:

window.ContactsX.delete(
   "877-568-ABC",
   function (oContact) {
      console.log(oContact);
   }, 
   function (oError) {
      console.error(oError);
   }
);

Objects

Contact

id (String) – a unique identifier
displayName (String) – Supported only on Android
firstName (String)
middleName (String)
familyName (String)
phoneNumbers (ContactPhoneNumber[])
emails (ContactEmail[])
addresses (ContactAddress[])

ContactPhoneNumber

id (String) – a unique identifier
type (String) – type of the phone number (e.g. “mobile”, “home”)
value (String)

ContactEmail

id (String) – a unique identifier
type (String) – type of the EMail address (e.g. “work”, “home”)
value (String)

ContactAddress

id (String) – a unique identifier
type (String) – type of the address (e.g. “work”, “home”)
street (String)
locality (String)
region (String)
postalCode (String)
country (String)

Error

code (Integer)
message (String)

Error Codes

The field code of Error object can have the following value which you can find in window.ContactX.ErrorCodes

1 – UnsupportedAction
2 – WrongJsonObject
3 – PermissionDenied
4 – CanceledAction
5 – NotFound
10 – UnknownError