1 |
|
2 | Licensed to the Apache Software Foundation (ASF) under one
|
3 | or more contributor license agreements. See the NOTICE file
|
4 | distributed with this work for additional information
|
5 | regarding copyright ownership. The ASF licenses this file
|
6 | to you under the Apache License, Version 2.0 (the
|
7 | "License"); you may not use this file except in compliance
|
8 | with the License. You may obtain a copy of the License at
|
9 |
|
10 | http://www.apache.org/licenses/LICENSE-2.0
|
11 |
|
12 | Unless required by applicable law or agreed to in writing,
|
13 | software distributed under the License is distributed on an
|
14 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
15 | KIND, either express or implied. See the License for the
|
16 | specific language governing permissions and limitations
|
17 | under the License.
|
18 | -->
|
19 |
|
20 | # org.apache.cordova.contacts
|
21 |
|
22 | This plugin defines a global `navigator.contacts` object, which provides access to the device contacts database.
|
23 |
|
24 | Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event.
|
25 |
|
26 | document.addEventListener("deviceready", onDeviceReady, false);
|
27 | function onDeviceReady() {
|
28 | console.log(navigator.contacts);
|
29 | }
|
30 |
|
31 | __WARNING__: Collection and use of contact data raises
|
32 | important privacy issues. Your app's privacy policy should discuss
|
33 | how the app uses contact data and whether it is shared with any other
|
34 | parties. Contact information is considered sensitive because it
|
35 | reveals the people with whom a person communicates. Therefore, in
|
36 | addition to the app's privacy policy, you should strongly consider
|
37 | providing a just-in-time notice before the app accesses or uses
|
38 | contact data, if the device operating system doesn't do so
|
39 | already. That notice should provide the same information noted above,
|
40 | as well as obtaining the user's permission (e.g., by presenting
|
41 | choices for __OK__ and __No Thanks__). Note that some app
|
42 | marketplaces may require the app to provide a just-in-time notice and
|
43 | obtain the user's permission before accessing contact data. A
|
44 | clear and easy-to-understand user experience surrounding the use of
|
45 | contact data helps avoid user confusion and perceived misuse of
|
46 | contact data. For more information, please see the Privacy Guide.
|
47 |
|
48 | ## Installation
|
49 |
|
50 | cordova plugin add org.apache.cordova.contacts
|
51 |
|
52 | ### Firefox OS Quirks
|
53 |
|
54 | Create __www/manifest.webapp__ as described in
|
55 | [Manifest Docs](https://developer.mozilla.org/en-US/Apps/Developing/Manifest).
|
56 | Add relevant permisions.
|
57 | There is also a need to change the webapp type to "privileged" - [Manifest Docs](https://developer.mozilla.org/en-US/Apps/Developing/Manifest#type).
|
58 | __WARNING__: All privileged apps enforce [Content Security Policy](https://developer.mozilla.org/en-US/Apps/CSP) which forbids inline script. Initialize your application in another way.
|
59 |
|
60 | "type": "privileged",
|
61 | "permissions": {
|
62 | "contacts": {
|
63 | "access": "readwrite",
|
64 | "description": "Describe why there is a need for such permission"
|
65 | }
|
66 | }
|
67 |
|
68 | ### Windows Quirks
|
69 |
|
70 | Any contacts returned from `find` and `pickContact` methods are readonly, so your application cannot modify them.
|
71 | `find` method available only on Windows Phone 8.1 devices.
|
72 |
|
73 | ### Windows 8 Quirks
|
74 |
|
75 | Windows 8 Contacts are readonly. Via the Cordova API Contacts are not queryable/searchable, you should inform the user to pick a contact as a call to contacts.pickContact which will open the 'People' app where the user must choose a contact.
|
76 | Any contacts returned are readonly, so your application cannot modify them.
|
77 |
|
78 | ## navigator.contacts
|
79 |
|
80 | ### Methods
|
81 |
|
82 | - navigator.contacts.create
|
83 | - navigator.contacts.find
|
84 | - navigator.contacts.pickContact
|
85 |
|
86 | ### Objects
|
87 |
|
88 | - Contact
|
89 | - ContactName
|
90 | - ContactField
|
91 | - ContactAddress
|
92 | - ContactOrganization
|
93 | - ContactFindOptions
|
94 | - ContactError
|
95 | - ContactFieldType
|
96 |
|
97 | ## navigator.contacts.create
|
98 |
|
99 | The `navigator.contacts.create` method is synchronous, and returns a new `Contact` object.
|
100 |
|
101 | This method does not retain the Contact object in the device contacts
|
102 | database, for which you need to invoke the `Contact.save` method.
|
103 |
|
104 | ### Supported Platforms
|
105 |
|
106 | - Android
|
107 | - BlackBerry 10
|
108 | - Firefox OS
|
109 | - iOS
|
110 | - Windows Phone 7 and 8
|
111 |
|
112 | ### Example
|
113 |
|
114 | var myContact = navigator.contacts.create({"displayName": "Test User"});
|
115 |
|
116 | ## navigator.contacts.find
|
117 |
|
118 | The `navigator.contacts.find` method executes asynchronously, querying the
|
119 | device contacts database and returning an array of `Contact` objects.
|
120 | The resulting objects are passed to the `contactSuccess` callback
|
121 | function specified by the __contactSuccess__ parameter.
|
122 |
|
123 | The __contactFields__ parameter specifies the fields to be used as a
|
124 | search qualifier. A zero-length __contactFields__ parameter is invalid and results in
|
125 | `ContactError.INVALID_ARGUMENT_ERROR`. A __contactFields__ value of
|
126 | `"*"` searches all contact fields.
|
127 |
|
128 | The __contactFindOptions.filter__ string can be used as a search
|
129 | filter when querying the contacts database. If provided, a
|
130 | case-insensitive, partial value match is applied to each field
|
131 | specified in the __contactFields__ parameter. If there's a match for
|
132 | _any_ of the specified fields, the contact is returned. Use __contactFindOptions.desiredFields__
|
133 | parameter to control which contact properties must be returned back.
|
134 |
|
135 | ### Parameters
|
136 |
|
137 | - __contactFields__: Contact fields to use as a search qualifier. _(DOMString[])_ [Required]
|
138 |
|
139 | - __contactSuccess__: Success callback function invoked with the array of Contact objects returned from the database. [Required]
|
140 |
|
141 | - __contactError__: Error callback function, invoked when an error occurs. [Optional]
|
142 |
|
143 | - __contactFindOptions__: Search options to filter navigator.contacts. [Optional]
|
144 |
|
145 | Keys include:
|
146 |
|
147 | - __filter__: The search string used to find navigator.contacts. _(DOMString)_ (Default: `""`)
|
148 |
|
149 | - __multiple__: Determines if the find operation returns multiple navigator.contacts. _(Boolean)_ (Default: `false`)
|
150 |
|
151 | - __desiredFields__: Contact fields to be returned back. If specified, the resulting `Contact` object only features values for these fields. _(DOMString[])_ [Optional]
|
152 |
|
153 | ### Supported Platforms
|
154 |
|
155 | - Android
|
156 | - BlackBerry 10
|
157 | - Firefox OS
|
158 | - iOS
|
159 | - Windows Phone 7 and 8
|
160 | - Windows (Windows Phone 8.1 devices only)
|
161 |
|
162 | ### Example
|
163 |
|
164 | function onSuccess(contacts) {
|
165 | alert('Found ' + contacts.length + ' contacts.');
|
166 | };
|
167 |
|
168 | function onError(contactError) {
|
169 | alert('onError!');
|
170 | };
|
171 |
|
172 | // find all contacts with 'Bob' in any name field
|
173 | var options = new ContactFindOptions();
|
174 | options.filter = "Bob";
|
175 | options.multiple = true;
|
176 | options.desiredFields = [navigator.contacts.fieldType.id];
|
177 | var fields = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name];
|
178 | navigator.contacts.find(fields, onSuccess, onError, options);
|
179 |
|
180 | ### Windows Quirks
|
181 |
|
182 | - `__contactFields__` is not supported and will be ignored. `find` method will always attempt to match the name, email address, or phone number of a contact.
|
183 |
|
184 | ## navigator.contacts.pickContact
|
185 |
|
186 | The `navigator.contacts.pickContact` method launches the Contact Picker to select a single contact.
|
187 | The resulting object is passed to the `contactSuccess` callback
|
188 | function specified by the __contactSuccess__ parameter.
|
189 |
|
190 | ### Parameters
|
191 |
|
192 | - __contactSuccess__: Success callback function invoked with the single Contact object. [Required]
|
193 |
|
194 | - __contactError__: Error callback function, invoked when an error occurs. [Optional]
|
195 |
|
196 | ### Supported Platforms
|
197 |
|
198 | - Android
|
199 | - iOS
|
200 | - Windows Phone 8
|
201 | - Windows 8
|
202 | - Windows
|
203 |
|
204 | ### Example
|
205 |
|
206 | navigator.contacts.pickContact(function(contact){
|
207 | console.log('The following contact has been selected:' + JSON.stringify(contact));
|
208 | },function(err){
|
209 | console.log('Error: ' + err);
|
210 | });
|
211 |
|
212 | ## Contact
|
213 |
|
214 | The `Contact` object represents a user's contact. Contacts can be
|
215 | created, stored, or removed from the device contacts database.
|
216 | Contacts can also be retrieved (individually or in bulk) from the
|
217 | database by invoking the `navigator.contacts.find` method.
|
218 |
|
219 | __NOTE__: Not all of the contact fields listed above are supported on
|
220 | every device platform. Please check each platform's _Quirks_ section
|
221 | for details.
|
222 |
|
223 |
|
224 | ### Properties
|
225 |
|
226 | - __id__: A globally unique identifier. _(DOMString)_
|
227 |
|
228 | - __displayName__: The name of this Contact, suitable for display to end users. _(DOMString)_
|
229 |
|
230 | - __name__: An object containing all components of a persons name. _(ContactName)_
|
231 |
|
232 | - __nickname__: A casual name by which to address the contact. _(DOMString)_
|
233 |
|
234 | - __phoneNumbers__: An array of all the contact's phone numbers. _(ContactField[])_
|
235 |
|
236 | - __emails__: An array of all the contact's email addresses. _(ContactField[])_
|
237 |
|
238 | - __addresses__: An array of all the contact's addresses. _(ContactAddress[])_
|
239 |
|
240 | - __ims__: An array of all the contact's IM addresses. _(ContactField[])_
|
241 |
|
242 | - __organizations__: An array of all the contact's organizations. _(ContactOrganization[])_
|
243 |
|
244 | - __birthday__: The birthday of the contact. _(Date)_
|
245 |
|
246 | - __note__: A note about the contact. _(DOMString)_
|
247 |
|
248 | - __photos__: An array of the contact's photos. _(ContactField[])_
|
249 |
|
250 | - __categories__: An array of all the user-defined categories associated with the contact. _(ContactField[])_
|
251 |
|
252 | - __urls__: An array of web pages associated with the contact. _(ContactField[])_
|
253 |
|
254 | ### Methods
|
255 |
|
256 | - __clone__: Returns a new `Contact` object that is a deep copy of the calling object, with the `id` property set to `null`.
|
257 |
|
258 | - __remove__: Removes the contact from the device contacts database, otherwise executes an error callback with a `ContactError` object.
|
259 |
|
260 | - __save__: Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same __id__ already exists.
|
261 |
|
262 | ### Supported Platforms
|
263 |
|
264 | - Amazon Fire OS
|
265 | - Android
|
266 | - BlackBerry 10
|
267 | - Firefox OS
|
268 | - iOS
|
269 | - Windows Phone 7 and 8
|
270 | - Windows 8
|
271 | - Windows
|
272 |
|
273 | ### Save Example
|
274 |
|
275 | function onSuccess(contact) {
|
276 | alert("Save Success");
|
277 | };
|
278 |
|
279 | function onError(contactError) {
|
280 | alert("Error = " + contactError.code);
|
281 | };
|
282 |
|
283 | // create a new contact object
|
284 | var contact = navigator.contacts.create();
|
285 | contact.displayName = "Plumber";
|
286 | contact.nickname = "Plumber"; // specify both to support all devices
|
287 |
|
288 | // populate some fields
|
289 | var name = new ContactName();
|
290 | name.givenName = "Jane";
|
291 | name.familyName = "Doe";
|
292 | contact.name = name;
|
293 |
|
294 | // save to device
|
295 | contact.save(onSuccess,onError);
|
296 |
|
297 | ### Clone Example
|
298 |
|
299 | // clone the contact object
|
300 | var clone = contact.clone();
|
301 | clone.name.givenName = "John";
|
302 | console.log("Original contact name = " + contact.name.givenName);
|
303 | console.log("Cloned contact name = " + clone.name.givenName);
|
304 |
|
305 | ### Remove Example
|
306 |
|
307 | function onSuccess() {
|
308 | alert("Removal Success");
|
309 | };
|
310 |
|
311 | function onError(contactError) {
|
312 | alert("Error = " + contactError.code);
|
313 | };
|
314 |
|
315 | // remove the contact from the device
|
316 | contact.remove(onSuccess,onError);
|
317 |
|
318 |
|
319 | ### Android 2.X Quirks
|
320 |
|
321 | - __categories__: Not supported on Android 2.X devices, returning `null`.
|
322 |
|
323 | ### BlackBerry 10 Quirks
|
324 |
|
325 | - __id__: Assigned by the device when saving the contact.
|
326 |
|
327 | ### FirefoxOS Quirks
|
328 |
|
329 | - __categories__: Partially supported. Fields __pref__ and __type__ are returning `null`
|
330 |
|
331 | - __ims__: Not supported
|
332 |
|
333 | - __photos__: Not supported
|
334 |
|
335 |
|
336 | ### iOS Quirks
|
337 |
|
338 | - __displayName__: Not supported on iOS, returning `null` unless there is no `ContactName` specified, in which case it returns the composite name, __nickname__ or `""`, respectively.
|
339 |
|
340 | - __birthday__: Must be input as a JavaScript `Date` object, the same way it is returned.
|
341 |
|
342 | - __photos__: Returns a File URL to the image, which is stored in the application's temporary directory. Contents of the temporary directory are removed when the application exits.
|
343 |
|
344 | - __categories__: This property is currently not supported, returning `null`.
|
345 |
|
346 | ### Windows Phone 7 and 8 Quirks
|
347 |
|
348 | - __displayName__: When creating a contact, the value provided for the display name parameter differs from the display name retrieved when finding the contact.
|
349 |
|
350 | - __urls__: When creating a contact, users can input and save more than one web address, but only one is available when searching the contact.
|
351 |
|
352 | - __phoneNumbers__: The _pref_ option is not supported. The _type_ is not supported in a _find_ operation. Only one `phoneNumber` is allowed for each _type_.
|
353 |
|
354 | - __emails__: The _pref_ option is not supported. Home and personal references same email entry. Only one entry is allowed for each _type_.
|
355 |
|
356 | - __addresses__: Supports only work, and home/personal _type_. The home and personal _type_ reference the same address entry. Only one entry is allowed for each _type_.
|
357 |
|
358 | - __organizations__: Only one is allowed, and does not support the _pref_, _type_, and _department_ attributes.
|
359 |
|
360 | - __note__: Not supported, returning `null`.
|
361 |
|
362 | - __ims__: Not supported, returning `null`.
|
363 |
|
364 | - __birthdays__: Not supported, returning `null`.
|
365 |
|
366 | - __categories__: Not supported, returning `null`.
|
367 |
|
368 | ### Windows Quirks
|
369 |
|
370 | - __photos__: Returns a File URL to the image, which is stored in the application's temporary directory.
|
371 |
|
372 | - __birthdays__: Not supported, returning `null`.
|
373 |
|
374 | - __categories__: Not supported, returning `null`.
|
375 |
|
376 |
|
377 | ## ContactAddress
|
378 |
|
379 | The `ContactAddress` object stores the properties of a single address
|
380 | of a contact. A `Contact` object may include more than one address in
|
381 | a `ContactAddress[]` array.
|
382 |
|
383 |
|
384 | ### Properties
|
385 |
|
386 | - __pref__: Set to `true` if this `ContactAddress` contains the user's preferred value. _(boolean)_
|
387 |
|
388 | - __type__: A string indicating what type of field this is, _home_ for example. _(DOMString)_
|
389 |
|
390 | - __formatted__: The full address formatted for display. _(DOMString)_
|
391 |
|
392 | - __streetAddress__: The full street address. _(DOMString)_
|
393 |
|
394 | - __locality__: The city or locality. _(DOMString)_
|
395 |
|
396 | - __region__: The state or region. _(DOMString)_
|
397 |
|
398 | - __postalCode__: The zip code or postal code. _(DOMString)_
|
399 |
|
400 | - __country__: The country name. _(DOMString)_
|
401 |
|
402 | ### Supported Platforms
|
403 |
|
404 | - Amazon Fire OS
|
405 | - Android
|
406 | - BlackBerry 10
|
407 | - Firefox OS
|
408 | - iOS
|
409 | - Windows Phone 7 and 8
|
410 | - Windows 8
|
411 | - Windows
|
412 |
|
413 | ### Example
|
414 |
|
415 | // display the address information for all contacts
|
416 |
|
417 | function onSuccess(contacts) {
|
418 | for (var i = 0; i < contacts.length; i++) {
|
419 | for (var j = 0; j < contacts[i].addresses.length; j++) {
|
420 | alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
|
421 | "Type: " + contacts[i].addresses[j].type + "\n" +
|
422 | "Formatted: " + contacts[i].addresses[j].formatted + "\n" +
|
423 | "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
|
424 | "Locality: " + contacts[i].addresses[j].locality + "\n" +
|
425 | "Region: " + contacts[i].addresses[j].region + "\n" +
|
426 | "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
|
427 | "Country: " + contacts[i].addresses[j].country);
|
428 | }
|
429 | }
|
430 | };
|
431 |
|
432 | function onError(contactError) {
|
433 | alert('onError!');
|
434 | };
|
435 |
|
436 | // find all contacts
|
437 | var options = new ContactFindOptions();
|
438 | options.filter = "";
|
439 | var filter = ["displayName", "addresses"];
|
440 | navigator.contacts.find(filter, onSuccess, onError, options);
|
441 |
|
442 | ### Android 2.X Quirks
|
443 |
|
444 | - __pref__: Not supported, returning `false` on Android 2.X devices.
|
445 |
|
446 | ### BlackBerry 10 Quirks
|
447 |
|
448 | - __pref__: Not supported on BlackBerry devices, returning `false`.
|
449 |
|
450 | - __type__: Partially supported. Only one each of _Work_ and _Home_ type addresses can be stored per contact.
|
451 |
|
452 | - __formatted__: Partially supported. Returns a concatenation of all BlackBerry address fields.
|
453 |
|
454 | - __streetAddress__: Supported. Returns a concatenation of BlackBerry __address1__ and __address2__ address fields.
|
455 |
|
456 | - __locality__: Supported. Stored in BlackBerry __city__ address field.
|
457 |
|
458 | - __region__: Supported. Stored in BlackBerry __stateProvince__ address field.
|
459 |
|
460 | - __postalCode__: Supported. Stored in BlackBerry __zipPostal__ address field.
|
461 |
|
462 | - __country__: Supported.
|
463 |
|
464 | ### FirefoxOS Quirks
|
465 |
|
466 | - __formatted__: Currently not supported
|
467 |
|
468 | ### iOS Quirks
|
469 |
|
470 | - __pref__: Not supported on iOS devices, returning `false`.
|
471 |
|
472 | - __formatted__: Currently not supported.
|
473 |
|
474 | ### Windows 8 Quirks
|
475 |
|
476 | - __pref__: Not supported
|
477 |
|
478 | ### Windows Quirks
|
479 |
|
480 | - __pref__: Not supported
|
481 |
|
482 |
|
483 | ## ContactError
|
484 |
|
485 | The `ContactError` object is returned to the user through the
|
486 | `contactError` callback function when an error occurs.
|
487 |
|
488 | ### Properties
|
489 |
|
490 | - __code__: One of the predefined error codes listed below.
|
491 |
|
492 | ### Constants
|
493 |
|
494 | - `ContactError.UNKNOWN_ERROR` (code 0)
|
495 | - `ContactError.INVALID_ARGUMENT_ERROR` (code 1)
|
496 | - `ContactError.TIMEOUT_ERROR` (code 2)
|
497 | - `ContactError.PENDING_OPERATION_ERROR` (code 3)
|
498 | - `ContactError.IO_ERROR` (code 4)
|
499 | - `ContactError.NOT_SUPPORTED_ERROR` (code 5)
|
500 | - `ContactError.PERMISSION_DENIED_ERROR` (code 20)
|
501 |
|
502 |
|
503 | ## ContactField
|
504 |
|
505 | The `ContactField` object is a reusable component that represents
|
506 | contact fields generically. Each `ContactField` object contains a
|
507 | `value`, `type`, and `pref` property. A `Contact` object stores
|
508 | several properties in `ContactField[]` arrays, such as phone numbers
|
509 | and email addresses.
|
510 |
|
511 | In most instances, there are no pre-determined values for a
|
512 | `ContactField` object's __type__ attribute. For example, a phone
|
513 | number can specify __type__ values of _home_, _work_, _mobile_,
|
514 | _iPhone_, or any other value that is supported by a particular device
|
515 | platform's contact database. However, for the `Contact` __photos__
|
516 | field, the __type__ field indicates the format of the returned image:
|
517 | __url__ when the __value__ attribute contains a URL to the photo
|
518 | image, or _base64_ when the __value__ contains a base64-encoded image
|
519 | string.
|
520 |
|
521 | ### Properties
|
522 |
|
523 | - __type__: A string that indicates what type of field this is, _home_ for example. _(DOMString)_
|
524 |
|
525 | - __value__: The value of the field, such as a phone number or email address. _(DOMString)_
|
526 |
|
527 | - __pref__: Set to `true` if this `ContactField` contains the user's preferred value. _(boolean)_
|
528 |
|
529 | ### Supported Platforms
|
530 |
|
531 | - Amazon Fire OS
|
532 | - Android
|
533 | - BlackBerry 10
|
534 | - Firefox OS
|
535 | - iOS
|
536 | - Windows Phone 7 and 8
|
537 | - Windows 8
|
538 | - Windows
|
539 |
|
540 | ### Example
|
541 |
|
542 | // create a new contact
|
543 | var contact = navigator.contacts.create();
|
544 |
|
545 | // store contact phone numbers in ContactField[]
|
546 | var phoneNumbers = [];
|
547 | phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
|
548 | phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
|
549 | phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
|
550 | contact.phoneNumbers = phoneNumbers;
|
551 |
|
552 | // save the contact
|
553 | contact.save();
|
554 |
|
555 | ### Android Quirks
|
556 |
|
557 | - __pref__: Not supported, returning `false`.
|
558 |
|
559 | ### BlackBerry 10 Quirks
|
560 |
|
561 | - __type__: Partially supported. Used for phone numbers.
|
562 |
|
563 | - __value__: Supported.
|
564 |
|
565 | - __pref__: Not supported, returning `false`.
|
566 |
|
567 | ### iOS Quirks
|
568 |
|
569 | - __pref__: Not supported, returning `false`.
|
570 |
|
571 | ### Windows8 Quirks
|
572 |
|
573 | - __pref__: Not supported, returning `false`.
|
574 |
|
575 | ### Windows Quirks
|
576 |
|
577 | - __pref__: Not supported, returning `false`.
|
578 |
|
579 |
|
580 | ## ContactName
|
581 |
|
582 | Contains different kinds of information about a `Contact` object's name.
|
583 |
|
584 | ### Properties
|
585 |
|
586 | - __formatted__: The complete name of the contact. _(DOMString)_
|
587 |
|
588 | - __familyName__: The contact's family name. _(DOMString)_
|
589 |
|
590 | - __givenName__: The contact's given name. _(DOMString)_
|
591 |
|
592 | - __middleName__: The contact's middle name. _(DOMString)_
|
593 |
|
594 | - __honorificPrefix__: The contact's prefix (example _Mr._ or _Dr._) _(DOMString)_
|
595 |
|
596 | - __honorificSuffix__: The contact's suffix (example _Esq._). _(DOMString)_
|
597 |
|
598 | ### Supported Platforms
|
599 |
|
600 | - Amazon Fire OS
|
601 | - Android 2.X
|
602 | - BlackBerry 10
|
603 | - Firefox OS
|
604 | - iOS
|
605 | - Windows Phone 7 and 8
|
606 | - Windows 8
|
607 | - Windows
|
608 |
|
609 | ### Example
|
610 |
|
611 | function onSuccess(contacts) {
|
612 | for (var i = 0; i < contacts.length; i++) {
|
613 | alert("Formatted: " + contacts[i].name.formatted + "\n" +
|
614 | "Family Name: " + contacts[i].name.familyName + "\n" +
|
615 | "Given Name: " + contacts[i].name.givenName + "\n" +
|
616 | "Middle Name: " + contacts[i].name.middleName + "\n" +
|
617 | "Suffix: " + contacts[i].name.honorificSuffix + "\n" +
|
618 | "Prefix: " + contacts[i].name.honorificSuffix);
|
619 | }
|
620 | };
|
621 |
|
622 | function onError(contactError) {
|
623 | alert('onError!');
|
624 | };
|
625 |
|
626 | var options = new ContactFindOptions();
|
627 | options.filter = "";
|
628 | filter = ["displayName", "name"];
|
629 | navigator.contacts.find(filter, onSuccess, onError, options);
|
630 |
|
631 | ### Android Quirks
|
632 |
|
633 | - __formatted__: Partially supported, and read-only. Returns a concatenation of `honorificPrefix`, `givenName`, `middleName`, `familyName`, and `honorificSuffix`.
|
634 |
|
635 | ### BlackBerry 10 Quirks
|
636 |
|
637 | - __formatted__: Partially supported. Returns a concatenation of BlackBerry __firstName__ and __lastName__ fields.
|
638 |
|
639 | - __familyName__: Supported. Stored in BlackBerry __lastName__ field.
|
640 |
|
641 | - __givenName__: Supported. Stored in BlackBerry __firstName__ field.
|
642 |
|
643 | - __middleName__: Not supported, returning `null`.
|
644 |
|
645 | - __honorificPrefix__: Not supported, returning `null`.
|
646 |
|
647 | - __honorificSuffix__: Not supported, returning `null`.
|
648 |
|
649 | ### FirefoxOS Quirks
|
650 |
|
651 | - __formatted__: Partially supported, and read-only. Returns a concatenation of `honorificPrefix`, `givenName`, `middleName`, `familyName`, and `honorificSuffix`.
|
652 |
|
653 |
|
654 | ### iOS Quirks
|
655 |
|
656 | - __formatted__: Partially supported. Returns iOS Composite Name, but is read-only.
|
657 |
|
658 | ### Windows 8 Quirks
|
659 |
|
660 | - __formatted__: This is the only name property, and is identical to `displayName`, and `nickname`
|
661 |
|
662 | - __familyName__: not supported
|
663 |
|
664 | - __givenName__: not supported
|
665 |
|
666 | - __middleName__: not supported
|
667 |
|
668 | - __honorificPrefix__: not supported
|
669 |
|
670 | - __honorificSuffix__: not supported
|
671 |
|
672 | ### Windows Quirks
|
673 |
|
674 | - __formatted__: It is identical to `displayName`
|
675 |
|
676 |
|
677 | ## ContactOrganization
|
678 |
|
679 | The `ContactOrganization` object stores a contact's organization
|
680 | properties. A `Contact` object stores one or more
|
681 | `ContactOrganization` objects in an array.
|
682 |
|
683 | ### Properties
|
684 |
|
685 | - __pref__: Set to `true` if this `ContactOrganization` contains the user's preferred value. _(boolean)_
|
686 |
|
687 | - __type__: A string that indicates what type of field this is, _home_ for example. _(DOMString)
|
688 |
|
689 | - __name__: The name of the organization. _(DOMString)_
|
690 |
|
691 | - __department__: The department the contract works for. _(DOMString)_
|
692 |
|
693 | - __title__: The contact's title at the organization. _(DOMString)_
|
694 |
|
695 |
|
696 | ### Supported Platforms
|
697 |
|
698 | - Android
|
699 | - BlackBerry 10
|
700 | - Firefox OS
|
701 | - iOS
|
702 | - Windows Phone 7 and 8
|
703 | - Windows (Windows 8.1 and Windows Phone 8.1 devices only)
|
704 |
|
705 | ### Example
|
706 |
|
707 | function onSuccess(contacts) {
|
708 | for (var i = 0; i < contacts.length; i++) {
|
709 | for (var j = 0; j < contacts[i].organizations.length; j++) {
|
710 | alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
|
711 | "Type: " + contacts[i].organizations[j].type + "\n" +
|
712 | "Name: " + contacts[i].organizations[j].name + "\n" +
|
713 | "Department: " + contacts[i].organizations[j].department + "\n" +
|
714 | "Title: " + contacts[i].organizations[j].title);
|
715 | }
|
716 | }
|
717 | };
|
718 |
|
719 | function onError(contactError) {
|
720 | alert('onError!');
|
721 | };
|
722 |
|
723 | var options = new ContactFindOptions();
|
724 | options.filter = "";
|
725 | filter = ["displayName", "organizations"];
|
726 | navigator.contacts.find(filter, onSuccess, onError, options);
|
727 |
|
728 | ### Android 2.X Quirks
|
729 |
|
730 | - __pref__: Not supported by Android 2.X devices, returning `false`.
|
731 |
|
732 | ### BlackBerry 10 Quirks
|
733 |
|
734 | - __pref__: Not supported by BlackBerry devices, returning `false`.
|
735 |
|
736 | - __type__: Not supported by BlackBerry devices, returning `null`.
|
737 |
|
738 | - __name__: Partially supported. The first organization name is stored in the BlackBerry __company__ field.
|
739 |
|
740 | - __department__: Not supported, returning `null`.
|
741 |
|
742 | - __title__: Partially supported. The first organization title is stored in the BlackBerry __jobTitle__ field.
|
743 |
|
744 | ### Firefox OS Quirks
|
745 |
|
746 | - __pref__: Not supported
|
747 |
|
748 | - __type__: Not supported
|
749 |
|
750 | - __department__: Not supported
|
751 |
|
752 | - Fields __name__ and __title__ stored in __org__ and __jobTitle__.
|
753 |
|
754 | ### iOS Quirks
|
755 |
|
756 | - __pref__: Not supported on iOS devices, returning `false`.
|
757 |
|
758 | - __type__: Not supported on iOS devices, returning `null`.
|
759 |
|
760 | - __name__: Partially supported. The first organization name is stored in the iOS __kABPersonOrganizationProperty__ field.
|
761 |
|
762 | - __department__: Partially supported. The first department name is stored in the iOS __kABPersonDepartmentProperty__ field.
|
763 |
|
764 | - __title__: Partially supported. The first title is stored in the iOS __kABPersonJobTitleProperty__ field.
|
765 |
|
766 | ### Windows Quirks
|
767 |
|
768 | - __pref__: Not supported, returning `false`.
|
769 |
|
770 | - __type__: Not supported, returning `null`.
|