Chandler Contact Project Documentation

This project took a 2006 summer of code (SoC) project by Ernesto Rivera and expanded on it as described in AddressBookDocumentation to fit the current chandler

Introduction

The previously mentioned summer of code project took the approach of making contacts a content item and storing them in a special collection called "Address Book". The current vision for contacts in chandler is to have contacts be a stamp, that can be applied to any note based item in chandler. This also includes a new Application bar view which allows the user to filter out contacts only.

The source code for this project can be found at : svn+ssh://svn.osafoundation.org/svn/sandbox/edbindl/contacts

Changes

The major change made from the SoC project is that Contacts are no longer inherited from Content Items but are now inherited from a stamp. Called a contact person stamp, these stamps can be applied to a note, to allow the user to store contact relevant information about a specific note. The ability to edit raw vCard was removed due to the unnecessary complications it creates. They were also some issues with the way the vObjects were stored as opposed to created when needed. In this version of contacts, vObjects are created as they are needed, which is during an import or an export to vCard.

Features

• Stampability of Notes with the ContactPersonStamp
• Editing of contacts using predefined fields
• Importing contacts from vCard (*.vcf) files (multiple contacts on a single file allowed).
• Exporting a collection of contacts to a single vCard (*.vcf) file.

Parcel overview

The parcel contains the following files:

• contacts/__init__.py

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

• contacts/contacts.py

  Defines the domain model (schema) definitions for the ContactPerson^? and ContactPersonStamp objects.

• contacts/importexport.py

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

• contacts/blocks.py

  Implements the main event handlers, detail views and attribute editors for these objects.

• 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). Note: This has not been updated since the SoC project and needs to be rewritten to support the new version of contacts.

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 is one kind of contact: ContactPersons. It's superclass is the Contact (not instanciable) abstract class which is itself a subclass of pim.Stamp. 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... It is very easy to support new vCard attributes as described below.

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'). As opposed to the SoC version, a vCard object is only instantiated when an import or export is done. It was unnecessary to store the vObj in the repository, as was being done before.

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:

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
    }
    ...

Known bugs and important missing features

Bugs from updated features:

• The image on the Application Bar button goes white after it is clicked on.
  • No insight to why this is happening

• There is a problem with adding the contact detail view to the existing detail view in chandler.
  • My implementation procedure was to get contacts working as a patch, and then move it into an installable parcel. I have been successful in moving everything to the parcel except for adding the button to the Markup Bar and adding the updated detail view to the existing note detail view. The solution most likely lies in the entry_points for the parcel. See the GData plugin for an example of how this works. Revision 1603 has the version of contacts and a patch to chandler in which contacts are closest to fully working.

• The naming of the attributes of ContactPersonStamp left over from the SoC project could be a lot better. They are too closely tied to the vCard naming and are not clear.

• Tests have not been updated to work with this version of contacts.

Bugs left over from the SoC project:

• 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

-- EdBindl - 16 Aug 2007