vCard for Developers

I’ve been researching vCard for a project involving contacts management. This is a quick overview on vCard aimed at developers, with a demo and stealing the example from wikipedia’s vCard entry. The official standard is here.

The Format

vCard is a standard for representing contact information, the kind of info you would see for a contact in an address book or email application – name, address, and so on. By convention, the file suffix is “.vcf”. The info is represented in a text file format as shown below:

BEGIN:VCARD
VERSION:2.1
N:Gump;Forrest (Name)
FN:Forrest Gump (Full Name)
ORG:Gump Shrimp Co.
TITLE:Shrimp Man
TEL;WORK;VOICE:(111) 555-1212
TEL;HOME;VOICE:(404) 555-1212
ADR;WORK:;;100 Waters Edge;Baytown;LA;30314;United States of America
LABEL;WORK;ENCODING=QUOTED-PRINTABLE:100 Waters Edge=0D=0ABaytown, LA 30314=0D=0AUnited States of America
ADR;HOME:;;42 Plantation St.;Baytown;LA;30314;United States of America
LABEL;HOME;ENCODING=QUOTED-PRINTABLE:42 Plantation St.=0D=0ABaytown, LA 30314=0D=0AUnited States of America
EMAIL;PREF;INTERNET:[email protected]
REV:20080424T195243Z
END:VCARD

As you can see, the format is an ugly mainframe-style format that belies vCard’s 1995 birthdate. If it was created a year or two later, it likely would have been a prettier XML format. But don’t be scared, it’s mostly harmless. You basically have field-value pairs separated by “:”. The standard defines all possible fields and the format for their values.

The Fields

The fields defined are: FN (full name – e.g. “Mr. Homer J. Simpson”), N (name – e.g. “Simpson;Homer”), NICKNAME, PHOTO, BDAY (birthday), ADR, LABEL, TEL, EMAIL, MAILER, TZ, GEO (lat/long co-ordinates), TITLE, ROLE, LOGO, AGENT (e.g. a secretary or personal assistant – this is a recursive vCard instance!), ORG, CATEGORIES, NOTE, PRODID (which product created the vCard), REV (a revision ID for this vcard instance), SORT-STRING (the “primary key” on which this record should be sorted, e.g. if you want ‘Van Winkle’ to be sorted as ‘Winkle’), SOUND, URL, UID, VERSION (the version of vCard used to generate this vCard), CLASS (a security access level for this vCard instance – e.g. is it public, protected, private?), KEY (a public key, e.g. you could use it if you wanted to send the contact something encrypted). The only mandatory fields here are FN and N (the two most obscurely named fields, naturally ;)).

Each field-value pair is something like a database record or an object instance, insofar as it includes a number of values. I guess the standard could have avoided this by defining 200 different field names, but instead they grouped related attributes together into the same field. So you end up with just a single “name” field (“N”), which is actually an aggregation of several fields. e.g. ” N:Stevenson;John;Philip,Paul;Dr.;Jr.,M.D.,A.C.P.” contains surname, first name, other names, title, and honorifics.

Similarly, field names are not always just a single word, but can also be qualified by type. Therefore “TEL;WORK;VOICE;PREF” is equivalent to “TEL;TYPE=WORK,VOICE,PREF” and also “TEL;TYPE=WORK,TYPE=VOICE,TYPE=PREF”. (The first form actually appears in the wikipedia example, but the standard talks about the second and third form, so any parser would have to read all of them.). The multiple types are effectively tags/keywords, i.e. the telephone number here is at once a work number, a number supporting voice interaction, and a preferred usage number.

Fields like logo and photo can either be a URL or binary data embedded directly in the VCARD.

See the official standard for full details.

MIME Gubbins: How to Serve vCard from your Web App

If you ever show contacts in your web app, it’s polite to include a vCard export option as users will appreciate the ability to pluck it off the site and into their preferred desktop app. I found serving it to be remarkably easy.

The demo is here

<?
  header('Content-Type: text/x-vcard; charset=utf-8');
  header('Content-Disposition: attachment; filename="vcard-example.vcf"');
?>
BEGIN:VCARD
VERSION:2.1
N:Gump;Forrest
FN:Forrest Gump
...
etc
....
END:VCARD

See? Just output those two headers, then bust out the vCard. The demo successfully opens in Apple Address Book and MS Outlook.

Apple Address Book

MS Outlook

So it works if you’re a Mac or a PC. Neat-O.

Portability, Limitations, and Variations

The great thing about standards is there are so many to choose from, as many a cynic has observed. The other great thing about most standards is they give you so much room for creativity, as this cynic responded. vCard is no exception and can be interpreted in different ways (whether or not these ways conform to the spec I don’t know, and is not especially relevant for real-world developers).

In particular, some people think a vCard file can include only one record, while others think it can include any number of records. I made a second demo to test this. The two-card demo is here. It contains one VCARD after another, as shown below. Well, Apple Address Book likes it and opens up both contacts, while MS Outlook ignores the second. So there.

<?
  header('Content-Type: text/x-vcard; charset=utf-8');
  header('Content-Disposition: attachment; filename="vcard-example.vcf"');
?>
BEGIN:VCARD
VERSION:2.1
N:Gump;Forrest
....
END:VCARD
BEGIN:VCARD
VERSION:2.1
N:Fump;Gorrest
....
END:VCARD

Furthermore, there are “extensions”, which are new property types that go beyond the standard and are used by certain applications. Wikipedia identifies a veritable menagerie of extensions, including such species as X-MANAGER for manager details; X-AIM/X-MSN/X-ICQ/X-GADUGADU (awesome!)/etc for IM details, and X-ASSISTANT for assistant details (they probably forgot about the AGENT property). any other properties are prefixed with the company who introduced them, leading to the elegantly named X-FUNAMBOL-YOMIFIRSTNAME property (this will soon become the sixth page on the internet to use that term).

Related Standards

vCard is closely related to a wider standard around directory formats, RFC 2425. This standard defines the basic, mainframe, field-value pair structure, as well as some basic types – SOURCE (source for the record, e.g. an LDAP server), NAME (name of the record, which will usually be the same a the vCard “N” field), PROFILE (vaguely defined as something about “how the record will be used”), BEGIN, END. BEGIN and END naturally appear in all vCards, but examples I’ve seen don’t use the other three types.

This W3C note attempts to XMLise vCard within an RDF framework.

hCard attempts to HTMLise vCard as part of the more-lightweight-than-RDF microformats initiative. (examples).

iCalendar, aka iCal and formally vCal (which sounds like vCard doesn’t it?) came from the Versit consortium around the same time as vCard…both intended for similar types of applications. iCal is about exchanging event information.

Ajax Functionality and Usability Patterns – Podcast 3 of 4: Visual Effects

This is the third in the four-part series on Ajax functionality and usability patterns (Book: Part 4, pp 327-530). An audio discussion of visual effects is ideally short and sweet, so this podcast is but 13 minutes long.

This 13-minute podcast covers ten patterns of Ajax Architecture (Book: Chapter 16, pp 445-472):

Ajax Functionality and Usability Patterns – Podcast 2 of 4: Ajax Page Architecture

This is the second in the four-part series on Ajax functionality and usability patterns (Book: Part 4, pp 327-530).

The guest for this week is Dave Johnson of Nitobi (the Ajax component developers formerly known as E-Business Applications), widget guru and author of the upcoming Enterprise Ajax book. Dave helps me walk through the patterns and offers plenty of great insights along the way. We mention Dave’s recent presentation a couple of times; here’s the PDF.

This 54-minute podcast covers ten patterns of Ajax Architecture (Book: Chapter 15, pp 389-444):

Ajax Functionality and Usability Patterns – Podcast 1 of 4: Widgets of the Web

And so, a new series begins, based on the Ajax functionality and usability patterns (Book: Part 4, pp 327-530). We’ve already looked at the technical details, now we’re looking at what Ajax can do for users and how to implement these features.

I’m asking guests to join me for most of the remaining Ajax Pattern podcasts. Seeing patterns from someone else’s perspsective will make the discussion richer and hopefully cover more questions you might have as you’re listening to the podcast. The guest for this week is Andre Charland of E-Business Applications, widget guru and author of the upcoming Enterprise Ajax book.

This 83-minute podcast covers nine patterns of Ajax widgets:

Ajax Programming Patterns – Podcast 4 of 4: Performance Optimisation Patterns

The fourth and final podcast in this series of Ajax Programming Patterns. As always, the patterns are online at AjaxPatterns.org and covered in the book too, now available at Amazon. This 33-minute podcast covers seven patterns of Performance Optimisation:

(Note that the last two are recent additions to the wiki and just stubs at this stage.)

Okay, here endeth the series. I will soon be starting up a new series on the next group of patterns (Part 5 in the book): Functionality and Usability Patterns. There will be a change in the format, one I hope you’ll enjoy!

Ajax Programming Patterns – Podcast 3 of 4: “DOM Population” and “Code Generation and Reuse” Patterns

The third podcast in this series of Ajax Programming Patterns. The 29-minute podcast covers five patterns. As with the previous podcast, there is reason for concern about the audio quality herein. Firstly, three patterns on DOM population – taking server response data and displaying it or storing it in the DOM:

The second group of patterns (representing a different chapter in the Ajax Design Patterns book) are a couple of generic Javascript patterns to make the code more maintainable and portable:

Ajax Programming Patterns – Podcast 2 of 4: Browser-Server Dialogue Patterns

Continuing from the previous podcast (cough 12 weeks ago), more programming patterns. Unfortunately, this recording (and the next one) went pear-shaped. Sorry. I do, however, recommend them to those of you who’ve been wondering what an Ajax talk would have sounded like in crackly 1930s recording technology, and one in which the speaker has a severe cold. FYI The level was too low and it didn’t correct very well…maybe one day, I’ll re-record, but for now I’d prefer to just get them out there as they have been sitting in the libsyn archive for many weeks.

The 40-minute podcast covers the following patterns:

  • Call Tracking Accommodate busy user behaviour by allocating a new XMLHttpRequest object for each request. See Richard Schwartz’s blog entry.Note: Pending some rewrite to take into account request-locking etc.
  • Periodic Refresh The browser refreshs volatile information by periodically polling the server.
  • Submission Throttling Instead of submitting upon each Javascript event, retain the data in a local buffer and upload it periodically.
  • Explicit Submission Instead of submitting upon each Javascript event, require the user to explicitly request it, e.g. submit upon clicking a button.
  • Distributed Events Keep objects synchronised with an event mechanism.
  • Cross-Domain Proxy Allow the browser to communicate with other domains by server-based mediation.

Click to download the Podcast. You can also subscribe to the
feed if you want future podcasts automatically downloaded - check out the
podcast FAQ at http://podca.st.

This podcast covers six patterns on Browser-Server Dialogue: Call Tracking, Periodic Refresh, Submission Throttling, Explicit Submission, Distributed Events,

Thanks for your feedback since last time. Good, bad, or ugly, it’s all welcome – in the comments for this podcast or [email protected]

Ajax Patterns Tutorial – Updated Docs

As just mentioned, I’ve posted code for the AjaxPatterns demos and the tutorial. You can run the tutorial here. The interesting thing here is it’s all designed to be hand-coded, so you can see how an Ajax app can easily be built up from first principles, good for learning. The final demo then uses an external library, to make the point that you don’t need to hand-code in the real world.

The Ajaxagram demo, with its various refactorings, is a useful way to introduce the patterns, and I covered it in Ajax Experience presentation. I’ve edited the overview page to help explain what value each refactoring is adding:

Ajaxagram: A Conventional Web App
No Ajax yet.

Ajaxifying Ajaxagram
Ajax version - runs in a single page without refresh. Basically the same user exeperience as before, but better for your resume and ready for the nice Ajax enhancements to come.

Enhancing Functionality and Usability
Now we’re actually seeing the benefits of Ajax. Three Functionality and Usability patterns are introduced to enhance the user experience – Live Search, Progress Indicator, One-Second Spotlight.

Streamlining Performance
Ooops, although it looks prettier and feels smoother, our app now has some technical issues. That’s a little side effect of most UI enhancements. Firstly, there’s a bug – if you type too quickly, you’ll see results for more than one search appear. Secondly, it’s too slow – we’re going back to the server every single keystroke. The Ajax patterns include Programming patterns to complement the Functionality and Usability patterns, and in this case, we remedy the situation with Submission Throttling.

Using An External Library
This final refactoring appears the same to users, but underneath the covers, we’ve introduced the ajaxCaller library to handle remoting. The point is to illustrate that Ajax Patterns don’t have to be hand-coded – many are easier to introduce with appropriate Ajax Frameworks and Libraries. There’s no shame in reusing reliable third-party code – it’s something to be proud of!

Ajax Programming Patterns – Podcast 1 of 4: Web Service Patterns

Whereupon a new podcast series begins …

As promised, a new series of Ajax pattern podcasts. This is the first of four podcasts on the Ajax programming patterns.

In this 73 minute podcast, we look at the seven patterns of web services as they relate to Ajax clients.

Click to download the Podcast. You can also subscribe to the
feed if you want future podcasts automatically downloaded - check out the
podcast FAQ at http://podca.st.

  • RPC Service Expose web services as Remote Procedural Calls (RPCs). (Note: In the book and wiki, REST appears before RPC.) (6:55)
  • RESTful Service Expose web services according to RESTful principles. (13:25 )
  • HTML Response Have the server generate HTML snippets to be displayed in the browser. (44:45)
  • Semantic Response Have the server respond with abstract, semantic, data. (49:00)
  • Plain-Text Message Pass simple messages between server and browser in plain-text format. (56:05)
  • XML Message Pass messages between server and browser in XML format. (57:20)
  • JSON Message Pass messages between server and browser in Javascript Object Notation (JSON) format. (59:55)

Thanks for your feedback since last time. Good, bad, or ugly, it’s all welcome – in the comments for this podcast or [email protected]

Basics of Ajax 3 of 3: Events and Much More (Podcast)

Ajax Basics 3 of 3

This is the final of three podcasts on the basic Ajax patterns.

  • Podcast 1: Display Patterns and the DOM.
  • Podcast 2: Web Remoting – XMLHttpRequest, IFrame Call, HTTP Streaming.
  • Podcast 3: Dynamic Behaviour – User Actions (Events), Timing, Ajax App, Web Service, On-Demand Javascript, Richer Plugin

Podcast 3: User Actions (Events), Timing, Ajax App, Web Service, On-Demand Javascript, Richer Plugin

Click to download the Podcast. You can also subscribe to the
feed if you want future podcasts automatically downloaded - check out the
podcast FAQ at http://podca.st.

This 77 minute podcast covers all the foundational technologies not yet covered in previous podcasts. Due to some reshuffling as the book was being edited, there are now four more patterns here than previously announced:

  • User Action Using the DOM’s event mechanism to deal with user actions such as mouse clicks (02:05)
  • Scheduling Schedule one-off or continuous events – Javascript code to run in the future (15:55)
  • Ajax_App The root of all Ajax (Note: The wiki version is empty at this time). Discussion of [Ajax Deluxe versus Ajax Lite]((http://www.softwareas.com/ajax-lite-versus-ajax-deluxe). (22:10)
  • Web Service The thing what sits on your server and gets called by the browser ‘n’ stuff (Note: The wiki version is empty at this time) (31:30)
  • On-Demand Javascript Remoting via Javascript – allows cross-domain remoting and lazy loading of modules (34:35).
  • Richer Plugin “Richer Plugin is an acknowledgement that Ajax alone is not always enough” (This pattern was the subject of the recent “What Ajax Can’t Do” debacle – Quote from Digg user: “This article is total crap.”) (48:20)

Featuring Ruby music by Why.

That completes the Basics series. Once the book is out of the way (Real Soon Now), expect to hear more Ajax pattern podcasts!

As always, feedback is welcome – [email protected]