Chandler Address Book Documentation (aka. contacts parcel)

This project has been updated! See ContactProject for the current status of the project

This document refers to code written on the scope of the AddressBookProject and only refers to implemented features. For pending tasks and and proposed features you should go to here instead.

Introduction

• The Address Book is the "contacts" parcel. Its code can be easily converted to a Python Egg using the same "setup.py" file included on the PyCon 2006 Sprint Code.
• The parcel has been tested on Mac OS X 10.4.x only.
• The parcel has been tested to work on Chandler 0.7alpha3.
• Most code written using ActiveState Komodo 3.5 on Mac OS X 10.4.

Features

• Creation of "Contact Persons" and "Contact Groups" items.
• Editing of contacts using predefined fields or directly modifying contact's "raw vCard code".
• Importing contacts from vCard (*.vcf) files (multiple contacts on a single file allowed).
• Exporting a collection of contacts to a single vCard (*.vcf) file.
• Test function to generate contacts by importing all vCard files stored on the "tests" parcel's directory.

Parcel overview

The parcel contains the following files:

• contacts/__init__.py

  Installs the parcel components (contacts, importexport and tests).

• contacts/contacts.py

  Defines the domain model (schema) definitions for the Contact, ContactPerson and ContactGroup objects. It also implements the main event handlers, detail views and attribute editors for these objects.

• contacts/importexport.py

  Handles vCard import/export events, initialization, dialogs and other related code.

• contacts/tests/__init__.py
  contacts/tests/tests.py

  Handles parcel's test events, initialization, dialogs and other related code. Currently only importing of vCards is implemented (import all vCard files from the tests directory).

Parcel details

Domain model changes (schema)

Firstly, the old contact model at osaf.pim.contacts has been left untouched to avoid conflicts with the current implementation. This parcel is a completely independent implementation of the Address Book. However as this parcel evolves it should replace the old one.

In this implementation there are two kinds of contacts: ContactPersons and ContactGroups. Both kinds have as their superclass the Contact (not instanciable) abstract class which is itself a subclass of pim.ContentItem. In more detail:

• Contact: abstract class, subclass of pim.ContentItem.
  • Attributes: groupMemberships.

• ContactPerson: subclass of Contact.
  • Attributes (most of them vCard equivalents): fn (formatted name), family, given, additional, org, title, address, etc... and also the "raw vCard code" field described below. It is very easy to support new vCard attributes as described below.
  • Methods: updateRawVCard (force updating contacts "raw vCard" field), updateVObj (updates the "vobject model" used to translate the contact to/from vCard)...

• ContactGroup: subclass of Contact and pim.ListCollection. Unfinished implementation.

Conditionally visible "raw vCard code" field (ContactPersons only)

This ContactPerson-only field is primarily meant for developers. It shows a "raw vCard code" representation of the contact and its changes as other contact fields are edited by the user. This can be useful to test the contact implementation and debugging without requiring constant vCard export.

This field can also be used to write vCard code by hand if desired. If vCard syntax errors are found the user is notified and the changes are reverted.

Ideally vCard code editing could highlight syntax errors.

Importing and exporting vCards (ContactPersons only)

The "native" contact attributes are converted to a vobject model (vObj) using an attribute mapping that describes the vCard equivalences (ex. 'zipcode' should map to vCard's 'adr.value.code'). This vObj model is synchronized every time a contact attribute is modified using the contact's detail view editors.

Multi-valued fields (ContactPersons only)

When a contact can have more than one value for a given attribute (ex. phones) then it is called a multi-valued attribute. Editing GUI fields for such attributes can be quite complicated as discussed here.

For this contact implementation a comma-separated values editor has been chosen:

vCard code generated for this multi-valued field:

Extending the parcel

Supporting new vCard attributes (ContactPersons only)

The parcel's code has been designed to make it easy to add and modify contacts' attributes.

Adding new contact fields takes only a few lines of code, all of them on the contacts.py file. Once the following steps are taken, exporting and importing vCards using those fields should "just work".

Attribute declaration

Define your new attributes:

class ContactPerson(Contact):
    ...
    singleAttr = schema.One(schema.Text) # a new single-valued attribute
    multiAttr = schema.Sequence(schema.Text) # a new multi-valued attribute
    ...

Vobject mapping

This is only required if you want the attributes to be imported and exported from/to vCards. Otherwise the attributes will be Chandler-only.

Add your attributes' vobject mapping (declare it's vCard equivalent):

class ContactPerson(Contact):
    ...
    VOBJ_MAPPING = {
        # single-valued fields
        ...
        'singleAttr': 'vcardattr.value', # singleAttr will be mapped to vobject.vcardattr.value
        'multiAttr': 'vcardattr', # multiAttr will be mapped to vobject.vcardattr
    }
    ...

Detail view

Add new GUI blocks to edit your new attributes:

def installContacts(parcel):
    ...
    contactPersonRootBlocks = [
        ...
        detail.makeArea(parcel,
            ...
            childrenBlocks = [
                detail.makeLabel(parcel, _(u"my single attribute"), borderTop=2),
                detail.makeSpacer(parcel, width=8),
                detail.makeEditor(parcel, 'singleAttr',
                    viewAttribute=u'singleAttr', # the attribute this editor will handle
                    presentationStyle={'format': 'contactSingleTextField'}, # required to sync raw vCard
            ]
        ...

For your multi-valued fields just use contactMultipleTextField instead of contactSingleTextField.

Known bugs and important missing features

• Due to limited time the Contact Group functionality is not functional.

• Import of entire directories is not available due to the wx file dialog not allowing directory selections. Multiple selections is not properly working either, as only one vCard will get imported (also a wx limitation?).

• Multi-valued fields tags are not implemented (ex. work/home/fax phones).

Comments