Closed Bug 772095 Opened 12 years ago Closed 12 years ago

Contacts API: Change type for ContactsEmail to String Array

Categories

(Core :: DOM: Device Interfaces, defect)

Product:
Core
Component:
DOM: Device Interfaces
Platform:
x86
macOS
Type:
defect
Priority:
Not set
Severity:
normal

Tracking

()

Status:
RESOLVED DUPLICATE of bug 782136

People

(Reporter: gwagner, Assigned: gwagner)

References

Details

Why do we want to do this? Exposing a whole array means that anyone building a contacts UI will have to figure out how to map the array in to their UI. Including things like being able to edit the type as needed, but also not modify the array if the user doesn't modify the type, or modifies it back to the value it was originally.

Going by https://wiki.mozilla.org/WebAPI/ContactsAPI#Methodology_for_inclusion this fails step 3 since as far as I know no other device exposes a full array in the UI.
> Exposing a whole array means that anyone building a contacts UI will have to figure out how to map the array in to their UI.

It doesn't mean that. There is no 1:1 API drives UI causality.  For example:

vCard format exposes an array, and there are plenty of phones that import/export vCards and thus have some sort of implementation (including UI) that handles it in some way. Do all phones support all of vCard? No. But they are able to handle import/export of a format that supports a whole array.

>I know no other device exposes a full array in the UI.

BlackBerry has multiple email addresses. MacOS AB supports multiple email addresses (with different types).

Both iOS and Android ABs support types (plural) for communication properties, as discerned by creating multiple phone numbers, and setting one of them to preferred, for each contact, and then exporting vCards, showing that the preferred phone number's type is exported as an array: "PREF,HOME" (e.g. for a home number).

Thus at a minimum for data portability fidelity from other platforms, we have to support importing the multiple types exported(emailed,shared,etc.) by iOS and Android AB. We can choose to support some simplified UI (e.g. looking for PREF in particular, and then assuming just one other type), but at the API level, we should reflect the interop layer between these, which is vCard, which has multiple types per communication address (tel, email, etc.)
Are we talking about the same feature? I totally agree that we should make it possible to have multiple email types. I.e. that on a given contact I should be able to say that the contact has two email addresses and the first one is a "private" address and the second one is a "work" address.

This is already possible in the current API. As far as I can tell that is all that iOS, gmail, android and Mac AB UI.


As far as UI goes, you definitely have to make the UI deal with a whole array for each email address if that is what we are exposing in the API. If the code receives an array like ["home", "work", "preferred", "starred"] in the type field then you definitely need to display something to the user in the UI. Additionally you have to make sure that if the user doesn't modify the type, that the same array is written back even if for example the email address is modified. Or if the user changes whatever the above renders as to just "home" and then change it back to whatever the above renders as.

However I would definitely be ok with exposing something like a boolean preferred flag on email/address/telephony, which we could then use when importing/exporting to vCard.
> As far as UI goes, you definitely have to make the UI deal with a whole array for each email address if that is what we are exposing in the API. If the code receives an array like ["home", "work", "preferred", "starred"] in the type field then you definitely need to display something to the user in the UI.

Not only is this reasoning false, but it has been disproven by nearly every shipping phone.

When importing vCards, *existing* phones can receive arrays like ["home", "work", "preferred", "starred"] in the type field, and then deal with it as best as they decided they needed to, ignoring/dropping what they feel like.

You don't "definitely need to display" all that to the user - as proven by the fact that no one does.  Address book support the standard types e.g. "pref" for meaning preferred or favorite phone number, and then the categories they already put in their UI. Some (e.g. Apple Address Book) support a customizable type where they put more.

Bottom line: people design the UIs they want for their users, and then support what they can of the API/format underneath.

No one that ships an address book says "here's everything that's exposed in the API, let's make the UI deal with all of it."
> When importing vCards, *existing* phones can receive arrays like ["home",
> "work", "preferred", "starred"] in the type field, and then deal with it as
> best as they decided they needed to, ignoring/dropping what they feel like.

How is that not "dealing with the full array"? If you choose to deal with it by dropping everything but the first item, then that's certainly an option, though it seems like a scary one to me.

> You don't "definitely need to display" all that to the user - as proven by
> the fact that no one does.

You cut my quote short. What I said was that you "definitely need to display something" which I still think is true.

It sounds like what we are proposing isn't that different. I propose that when importing from vCard, the importing tool will decide how to deal with collapsing the array into a single value. Then any application can display that single value in its UI.
> If you choose to deal with it by dropping everything but the first item, then that's certainly an option, though it seems like a scary one to me.

I agree that's a scary one, and that's not what current implementations do.

E.g. I just tried creating a simple "Test" contact in MacOS AB (Lion), added two phone numbers, chose "work fax" for the first, and "home fax" for the second (both from their default pop-up menu - no other/customization), exported it as VCF (drag contact to desktop). Verified in a text editor that:

* Apple Address Book exports *multiple* types (array) for each phone number
 * 3: work,fax,pref for the first number
 * 2: home,fax for the second number

And then I edited the VCF to be the name "Alice Test" and imported it, and everything round-tripped into the new contact, with two phone numbers, the first with type "work fax", and the second with type "home fax".

So the point is, they're supporting multiple types (array) per phone number, both at the API layer (vCard) and to a lesser extent the UI layer (from a user perspective, "work fax" looks like one type, but from the API layer, it looks like 2, or 3 if it happens to be the first phone number in the list).

I'm proposing we do the same (pending UI review of course), that from the user perspective we give them a simple flat list, but break it out at the API/format layer into the same types as other implementations (e.g. MacOS AB) for interop/compat. 

This decision (when to break/combine types) MUST happen in the UI/App layer, as once it hits the API, any user context is lost, and it can't make any "smart" decisions about when/if/how an apparently flat string should be broken into multiple strings, and when it should not.

Thus the API must directly reflect the schema of format layer we want to for interoperability, vCard, more than the quirks/idiosyncrasies of any particular version/vendor of an Address Book UI.
I don't understand "And then I edited the VCF to be the name "Alice Test""

I'm also not sure what the point is. Unless they expose the whole array in the addressbook UI, then what is the use-case for having an array in the API?

It sounds to me like the API we currently have allows vCard export tools to create an array like ["work", "fax"] if the type is set to "work fax". Likewise it can add "pref" to the type of the first email entry.
> I'm also not sure what the point is.

The conclusion of the reasoning at the end of my comment:

"Thus the API must directly reflect the schema of format layer we want to for interoperability, vCard, more than the quirks/idiosyncrasies of any particular version/vendor of an Address Book UI."


> Unless they expose the whole array in the addressbook UI, then what is the use-case for having an array in the API?

See above. API does not dictate a specific UI but rather enables possible UIs.  Prefacing a 1:1 correspondence assumption ("expose the whole array") with "Unless" does not make it so. 

An array of types in the API allows for multiple *actual* UIs, the MacOS Apple Address Book UI is but one example as demonstrated. That's a sufficient existence proof of the variability of UI vs. API. We can demonstrate with other actual UIs as well but the point remains.

The commonality among them is an array of types.

> It sounds to me like the API we currently have allows vCard export tools

This sounds like you're under a mistaken assumption that "vCard export tool" is somehow different from "Address Book". It's not.

On MacOS, iOS, Android, Outlook, etc., each of their "Address Book" app has vCard export and import as a *feature*. It's not a separate tool. It's part of the app.

So in that regard, yes, our Address Book app, can create an API array like ["work", "fax"] if the UI type is set to "work fax". Likewise it can add "pref" to the type of the first email entry.
Status: NEW → RESOLVED
Closed: 12 years ago
Resolution: --- → DUPLICATE
You need to log in before you can comment on or make changes to this bug.