To start developing the imip-agent software further, first obtain the code by following the advice on the downloads page. Obtaining the code directly from the repository is advisable since any changes you make can then be tracked and managed.
The software distribution contains the following directories:
Directory | Description |
conf | Example configuration files (see the getting started guide for details) |
docs | Documentation, including these wiki pages |
htdocs | Resources for the management interface |
imiptools | A Python package providing mail handling and support for calendar object processing |
imipweb | A Python package providing Web-related functionality for the management interface |
messages | Localised messages for the agent programs and management interface |
tests | A suite of tests used to verify the behaviour of the software (see the testing guide) |
tools | Tools for administration (see also the getting started guide) |
At the top level of the distribution, the following files are found:
File | Description |
imip_person.py | The main program files for the agent programs |
imip_person_outgoing.py | |
imip_resource.py | |
imip_manager.py | The management interface main program file |
markup.py | A Python library providing HTML generation support |
README.txt | Some basic documentation |
vCalendar.py | Handling of vCalendar and related data formats |
vContent.py | |
vRecurrence.py |
The principal components of the software architecture are described below.
The v-prefixed libraries are concerned with the basic interpretation of calendar-related data. For the most part, these libraries should already behave in a predictable and reliable fashion and should not need much further development. There are perhaps some deficiencies in the vRecurrence module that are described on the calendaring standards page.
It is not inconceivable that a vCard module be introduced in the future to handle vCard data, thus enhancing the data about people within imip-agent, perhaps also supporting mechanisms to obtain free/busy and other information about scheduling participants.
The bulk of the work done in imip-agent happens within imiptools. When used from agent programs launched by the mail system, the different modules support the "handler" functionality that involves obtaining information from calendar data, performing the necessary action related to a scheduling method, and generating responses or notifications. More details are given about these activities in the guide to incoming message handling.
When used from the management interface, the modules support the Web-based functionality as a more general calendar system client, typically handling a single calendar object at any given time.
The imiptools.stores package provides the basis for calendar data persistence. From the very start, the nature of data organisation for calendar users was centred on the storage of each user's free/busy records, since the priority was to generate such records from messages exchanged over e-mail, and the use of plain text files was chosen as the simplest and most transparent approach. Beyond this, the need to retain calendar objects arose, and thus a filesystem-based approach was cultivated to manage such data.
In the future, other persistence mechanisms could be supported. However, aside from performance concerns around access to free/busy schedules, there may be no urgent need to adopt relational database technologies, particularly as each user's data should remain isolated from that of other users, and thus the volumes of data should remain relatively small if managed well enough.
Most of the imipweb package is concerned with the display of calendar information as Web pages and the handling of submitted data over the Web as users interact with those Web pages. The imip_manager.py file is deployed as a CGI program, and it acts as a simple "switch" that shows the appropriate kind of Web page (or "view") depending on the requested URL, delegating to one of the modules within the imipweb package to do so:
| Module | View |
| imipweb.calendar | Calendar |
| imipweb.event | Individual events |
| imipweb.profile | User profile |
A general imipweb.resource module supports the different views with common functionality. Useful abstractions for period and date information are provided in the imipweb.data module. The CGI interfacing is defined in the imipweb.env module.
One of the most awkward aspects of providing a Web interface to events is the need to provide a comprehensive enough representation of period data as expressed in calendar objects that can be held in a form defined in a Web page, interpreted by the program, written back to the form, all without losing information.
The traditional gettext mechanisms for translating labels, messages and other user-readable strings are employed in the imip-agent code. Some tools have been provided to maintain this localisation.
To extract "messages" from the code, run the tools/i18n_messages.sh script:
tools/i18n_messages.sh
This produces a file called imip-agent.pot in the current directory, and it also attempts to merge any new messages into the existing message translations found in the messages directory. Such translation files have the following form:
messages/xx_XX.imip-agent.po
Here, xx is usually an ISO 639-1 language code, whereas XX is usually an ISO 3166-1 country code.
Translators should inspect and edit their files in the messages directory and then use the tools/i18n_format.sh script to generate the translations that the software will use:
tools/i18n_format.sh
This installs the "compiled" translations into the locale directory in a location of the following form:
locale/xx_XX/LC_MESSAGES/imip-agent.mo
The tools/install.sh script will copy the locale directory into the installation location unless the --no-locale-dir option is given. This is provided to allow any centrally-installed translations to take precedence over any locally-available translations.