20041025 OPENWEBMAIL NEW VCARD ADDRESSBOOK:
-- BETA! NOT PRODUCTION READY! --
The code here has NOT been tested worldwide. Although every effort has been made to eliminate
any possible errors, it is STRONGLY recommended that this code NOT be run in a production
environment until it can be tested by a larger user base.
PLEASE READ ALL INFORMATION BEFORE INSTALLING THIS PATCH SET
INTRODUCTION:
On October 6, 2003 I wrote an email to the lead developers requesting
clearance to develop the new OpenWebMail addressbook. Little did I realize that is would take
over a year of working in my free time to get all the technology in place and create the patch!
The main problem with creating a vCard compliant addressbook system in Perl is that there
did not exist a full vCard implementation in Perl anywhere. There were partial implementations,
but most did not exploit the full power of the vCard specification. The AGENT, KEY, and often
any Base64 translations were not supported. Additionally, no implementation supported both
vCard 2.1 and vCard 3.0 parsing and output.
The implementations that did exist did not, in my opinion, create the perl data structures with
the flexibility of the vCard file format in mind. Since any propertyname can contain any number
of types it is important that the data structure accomodate this. Since a vCard can contain
any number of propertynames, including the same propertyname multiple times, it is important that
this too is supported in the vCard data structure. Each propertyname can also be grouped per the
RFC, so grouping should also be supported.
Other issues included no base support for the vFile specification, which could be used to parse
other vFile objects such as vCal, vEvent, vTodo, vJournal, vFreeBusy, and vTimezone. A standard
vFile parser is important to reduce time to realization of other v-type formats in the future.
To solve these problems I broke this project into two phases. Phase I would be the implementation
of the vCard specification in procedural Perl. Phase II would be the exploitation of that
implementation in a web based interface that is fully integrated into the OpenWebMail system.
PHASE I:
The vCard technology created for this project rigidly follows the vCard RFC specifications:
vCard 2.1 Specification: Postscript Rich Text
vCard 3.0 MIME Content-Type RFC2425: Text
vCard 3.0 MIME Directory Profile RFC2426: Text
The vCard implementation created for OpenWebMail is the first implementation I have
ever seen that fully implements the RFC, including complete vCard agent support, proper character
escaping, proper line wrapping, and proper line encoding per the vCard VERSION propertyname.
All vCards stored in the OpenWebMail system are stored in the vCard version 3.0 format.
I have written a preliminary guide to the vCard data structure used in the addressbook patch.
This is helpful reading for people who want to contribute an import / export routine or just
understand the vCard data structure used in OpenWebMail.
It doesn't flow very well yet and mabye leaves some questions unanswered, but its still
helpful for an overview of whats happening.
PHASE II:
This patch set is a complete rewrite of the OpenWebMail Addressbook system. The new system
implements a completely vCard compliant system that is extendable and modular. vCards can be
exchanged with any contact software out in the mainstream. This brings OpenWebMail up to
date with current address technology and allows sharing of addressbook information among users.
There were many required changes to OpenWebMail. A brief summary includes:
1) The following new icons have been added:
abookunselectall.gif
abookexport.gif
abookgeofind.gif
abookimport.gif
abooknewcontact.gif
abooknewgroup.gif
abooks.gif
abookviewselected.gif
abookagent.gif
abooksound.gif
abookgeocamera.gif
abookglobalicon.gif
abookkey.gif
The following icons have been removed:
export.gif
All Text* iconset files have been updated.
2) The following new options have been added to etc/default/openwebmail.conf:
enable_addressbook
abook_maxsizeallbooks
abook_globaleditable
abook_importlimit
abook_attlimit
default_abook_addrperpage
default_abook_collapse
default_abook_sort
default_abook_listviewfieldorder
Corresponding descriptions have been written in openwebmail.conf.help (translators please translate)
3) The following template files have been added to etc/templates/$$ (translators please translate):
addrbookedit.template
addrcomposeselect.template
addreditform.template
addreditform_ADR.template
addreditform_BDAY.template
addreditform_GENERIC.template
addreditform_GEO.template
addreditform_KEYAGENT.template
addreditform_N.template
addreditform_ORG.template
addreditform_PHOTO.template
addreditform_TEL.template
addreditform_X-OWM-CUSTOM.template
addreditgroupform.template
addrexportbook.template
addrimportbook.template
addrlistview.template
addrshowchecked.template
displaynote.js
The following template files have been removed:
addressbook.template
editaddresses.template
importabook.template
The following templates were modified (translators please re-translate):
prefs.template
composemessage.template (code only - no translation necessary for this file)
4) All etc/lang files have been updated to include the many new entries required.
5) New shared code has been added in /shares:
adrbook.pl - standard routines for reading and writing addressbooks
vfile.pl - the vfile base parser for extracting vfile objects from files or strings
vcard.pl - the vcard parser/output module
The following shared files have been modified:
ow-shared.pl
6) The following files have been modified in the /modules directory:
tool.pl - add mime support for pgp,gpg,au,vcf,vcard and many other types
7) The main code blocks have been modified:
openwebmail-abook.pl - The new addressbook routines
openwebmail-prefs.pl - support for new options
openwebmail-tool.pl - support for mass converting addressbooks
openwebmail-send.pl - support for access to the new addressbook during compose
openwebmail-main.pl - moved address icon
openwebmail-read.pl - add sender address
INSTALLATION:
These patches are against:
MD5 sum:
b59fccecf4736e239aa40d2a673138eb openwebmail-current.tar.gz
File Info:
6302500 Oct 23 08:06 openwebmail-current.tar.gz
It is assumed that administrators downloading and installing this patch know how to
download and extract OpenWebMail. These patches also assume that the structure of
OpenWebMail is exactly the same as the tar file. Please do any customizations AFTER
applying the patch set and following the instructions below.
Please follow these procedures to install the new addressbook system:
1) Download the patch set files to the PATH_TO_OPENWEBMAIL directory on your machine.
2) Change to the PATH_TO_OPENWEBMAIL directory
3) Extract and apply the text patches by typing the commands:
tar -xvzf SUPERPATCH.patch.tgz
patch < SUPERPATCH.patch
The machine will go crazy as it applies a bazillion lines of code to 952 files
in order to install the new addressbook system.
4) Extract the binary files to their proper directories using the command:
tar -xvzf newicons.tgz
The new icons will be extracted and placed into their proper directories.
5) Remove the unused icons by typing the command:
rm -v data/openwebmail/images/iconsets/*/export.gif
All occurances of export.gif will be removed.
6) Translate the lang file that applies to your language BEFORE running the new code.
WHY?
The new addressbook obviously does not use the old addressbook format. Old addressbooks
are converted to vCards when a user accesses the account.
Unfortunately, the old addressbook format did not specify last or first name fields. We
have no way of knowing if the name in the name field is a first name, last name, or any
other type of data. So, in all cases the name field that the old entry had is put into
the last name property of the vCard. It is put in its entirety, spaces and all, even
if that doesn't make sense for a last name (we have no way of knowing). So what about the
first name of the vCard? The first name property for each entry is set to whatever
value exists in the language file under the entry:
abook_converted => 'Converted:',
So for example, let say we have an old addressbook entry like:
Elliott Smith@@@esmith@verymissed.com@@@
The new vCard entry after conversion will have name properties like:
N:Elliot Smith;Converted:;;;
FN:Converted: Elliot Smith
and will appear in the listview as:
Converted: Elliott Smith
So, you can see that it is important that you set the abook_converted value BEFORE accessing
addressbook data that will be converted so that the text that is used for 'Converted:'
is correct for you and your users' language.
7) Update the cgi-bin/openwebmail/etc/openwebmail.conf file to your settings. Make sure you
consider the settings for the new configuration parameters listed above in summary section 2.
8) Convert your global addressbook to the new format using the command:
./cgi-bin/openwebmail/openwebmail-tool.pl --convert_addressbooks
The Global Addressbook is not converted automatically if it is in the old format,
so it must be done manually BEFORE using the new system.
A backup of the current Global Addressbook is made before it is converted. The backup
is located in the same directory as your Global Addressbook as specified in your
cgi-bin/openwebmail/etc/openwebmail.conf file. The backup file has the same name
as your Global Addressbook, but with ".old" appended to it.
9) THIS STEP IS OPTIONAL.
Optionally, you may want to pre-convert all user addressbooks instead of having them
converted on the fly as users access the new system for the first time.
To mass-convert all user addressbooks to the new vCard system type the command:
./cgi-bin/openwebmail/openwebmail-tool.pl --convert_addressbooks --alluser
Whenever user addressbooks are converted, whether it is manually or on the fly, a
couple of things happen. First, a new directory is made to store addressbooks for
that user at PATH_TO_USER_DATA/webaddr. Second, the users existing addressbook in the
old format is moved into the new webaddr folder, but is named .address.book.old. A new
addressbook is created named after the value of the lang variable 'abook_converted'
that contains all of the new vCard addressbook data that was converted.
10) Apply any customizations you normally do.
You are done! Try it out!
DOWNLOADS:
One massive patch file and one tar file are required to implement the new addressbook:
- SUPERPATCH.patch.tgz 4002704 bytes uncompressed! tgzMD5:7ae9e4d35ddd3692e093d558c67d9f99
- newicons.tgz 48115 bytes MD5:12aa328b78f8b6adaec133ac280a979d
This set of patches has been tested on many browsers including:
Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.5) Gecko/20031007 Firebird/0.7
Windows XP Professional Version 2002 Service Pack 1
Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.7) Gecko/20040714 Firefox/0.9.1
FreeBSD 4.9-RELEASE
Mozilla/5.0 (Windows; U; Win98; en-US; rv:0.9.2) Gecko/20010726 Netscape6/6.1
Windows 98 Second Edition 4.10.2222A
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:0.9.9) Gecko/20020408
Redhat 7.2 Linux (2.4.18-3)
Mozilla/5.0 (Windows; U; Win98; en-US; rv:1.0.0) Gecko/20020530
Windows 98 Second Edition 4.10.2222A
Internet Explorer Version 5.0 (2022)
Mac OS 9.2.2
Internet Explorer Version 5.2.2 (5010.1)
Mac OS X 10.2.8 (6R73) Darwin Kernel Version 6.8
Internet Explorer Version 6.0.2600.0000.xpclient.010817-1148
Windows XP Professional Version 2002
Internet Explorer Version: 6.0.2800.1106.xpsp1.020828-1920CO
Windows XP Professional Version 2002 Service Pack 1
Internet Explorer Version: 6.0.2800.1106
Windows 98 Second Edition 4.10.2222A
Opera Version 7.22 Build 3221 Platform Win32 System Windows 98
Windows 98 Second Edition 4.10.2222A
Konquerer 3.1.1 (Using KDE 3.1.1a)
FreeBSD 4.8-RELEASE
Safari 1.0.1 (v85.6)
Mac OS X 10.2.8 (6R73) Darwin Kernel Version 6.8
Camino v0.7 Build 2003030613
Mac OS X 10.2.8 (6R73) Darwin Kernel Version 6.8
Netscape Communicator 4.7
Windows 98 Second Edition 4.10.2222A
IRIX 6.5
NOTES:
-It should be noted that none of the import/export filters have been incorporated into
the new system. I just wanted to get the code out. Others can do this work (and some already
have a head start!).
-Many of the new icons do not match their iconset. I did not have time to make iconsets for
every new icon. So, I leave this task up to the graphic designers out there.
-I have left in all of the debugging code, just in case there is some more bug squashing to do.
SCREENSHOTS:
Standard listview window
New preferences
Bunch of addresses checked
The "viewchecked" view of the checked addresses
The listview with the expand option (the little blue arrow next to move/copy dropdown)
The import screen
The export screen
The Books screen where you can add/delete/rename addressbooks
The contact edit form page. Every field you could ever want!
The group edit page
FUTURE:
-An icon next to each user in the listview that displays all of their info in a popup like the notes popup
would be cool and handy. Right now to see extended user data you must access the contact in edit mode.
-Now that there is a method to store PGPKey data for each user, the door is open for PGP support!
-I'm sure there will be a flurry of patches as bugs are found. Report them to me on the forum!
forum.openwebmail.org.
THANKS:
-My girlfriend, who is the most patient person in the world with me and my projects.
-Tung for waiting for so long, giving me good advice numerous times, and trusting me
that I would finish it...eventually. :)
-Joao Viega for the CSV import routines (I didn't have time to put them in yet - sorry!)
-Sergio (aka barbuto) for his Adjunct Icon sets.
-Gareth Horth for his extended addressbook patch. First for writing it, second for not getting
upset that it didn't get added to the main code, and finally for inspiring me towards a cleaner
interface.
If you enjoy this patch please consider donating to:
The OpenWebMail Project
ENJOY!
Alex