icemac.addressbook 1.10.1

Multi user address book application

icemac.addressbook

Purpose: Store, search and export addresses and phone numbers using a web application.

Status: version used in production but still missing some functionality (See To do)

Contents

• icemac.addressbook

• Features

  • General

  • Data

  • Search & Export

  • Technical

• Screenshots

• Hacking

• Installation

  • Prerequisites

  • Package installation

    • First installation

    • Update

    • Second part of steps for really old versions

  • Source installation

  • Run the tests

  • Run the application

  • Change configuration of the installation

• User management

  • Roles

  • Create new users

• To do

  • Next major version

  • Longer term

• Change log

  • 1.10.1 (2013-06-25)

  • 1.10.0 (2013-06-21)

    • Features

    • Other

  • 1.9.0 (2012-12-29)

    • Features

    • Bugfixes

    • Other

  • 1.8.1 (2012-04-20)

    • Features

    • Bugfixes

    • Other

  • 1.8.0 (2011-12-14)

    • Features

    • Bugfixes

    • Other

  • Previous Versions

• Download

Features

General

• multi-client capability

• user and role management

• Completely translated into German, and easily translateable into other languages.

• Optimized for the following browsers: Firefox, Safari. IE works but might look ugly. (Mobile version of Safari has some glitches.)

Data

• store data of persons including postal address, e-mail address, home page address, phone number and files

• add data fields to persons and addresses using the user interface

• ability to change the oder of the fields of persons and adresses

• assign keywords to persons

• import data from XLS (Excel) or CSV files

Search & Export

• search for persons by keywords and names

• export persons found using a search as XLS file

• update a single field of multiple persons as returned by a search (multi-update)

Technical

• really good test coverage of program code (> 98 %)

• data storage is an object database (ZODB) so no additional database is required

Screenshots

See SourceForge.

Hacking

Fork me on: https://bitbucket.org/icemac/icemac.addressbook

See Source installation, too.

Installation

Prerequisites

• You only need Python 2.6.x. (Other Python versions are currently not supported.)

There are two variants for installation:

• Package installation (to be preferred)

• Source installation (for development)

Package installation

Follow these steps if you want to install the pre-packaged address book (preferred way):

First installation

CAUTION: icemac.addressbook can’t be installed using easy_install or pip, you have to follow these simple steps.

Neither you need any root privileges nor it installs anything outside its directory.

1. Download the source distribution (see Download).

2. Extract the downloaded file.

3. Run install.py using your desired python, e. g.:

   $ python2.6 install.py

4. Answer the questions about admin user name, password and so on.

5. Run the tests. See Run the tests

6. Start the application. See Run the application

Update

• If you are updating from version 0.3.x or earlier follow the steps described in First installation followed by the steps described in Second part of steps for really old versions.

• If you are updating from version 0.4 or newer follow these steps:

  1. Download and extract the source distribution (see Download) to a new a directory.

  2. Run install.py using your desired python added by the path to the previous installation. This way values you entered previously are used as defaults instead of the application defaults. Example:

  $ python2.6 install.py ../icemac.addressbook-0.4

  3. Answer the questions about admin user name, password and so on.

  4. Start the new instance of the application.

• If you get an error when running the application after updating which looks like:

  zope.generations.interfaces.UnableToEvolve: (..., u'icemac.addressbook', ...)

  • If you upgrade from version 0.x then you have to upgrade to version 0.5.4 first and start the application, so that legacy data can be converted. Version 1.x is no longer compatible with these older versions.

  • You might need to not install any additional packages during these upgrade steps as the installer always tries to install the newest versions of the additonal packages which might not be compatible with the older versions.

Second part of steps for really old versions

1. Stop the old instance of the application.

2. Create a backup of the ZODB og the old instance using:

   $ bin/backup

3. Copy the backup directory (var/backups) to the new instance.

4. Restore the backup into the new instance using:

   $ bin/restore

5. Start the new instance of the application.

Source installation

1. Get the source code:

   $ hg clone https://bitbucket.org/icemac/icemac.addressbook

2. Install the sources:

   $ cd icemac.addressbook
   $ printf "[buildout]\nextends = profiles/%s\n" dev.cfg > buildout.cfg
   $ python2.6 bootstrap.py
   $ bin/buildout

Run the tests

Running the tests is independent from your choosen installation kind.

Run the unit tests and functional tests using:

$ bin/test

To run the Selenium tests you additionally need: a running Selenium Server. Download “Selenium Server” from SeleniumHQ. Start it like any other jar package is started on your operating system. Run all tests using:

$ bin/test --all

Run the application

Running the application is independent from your choosen installation kind.

To run the application instance in foreground start using:

$ bin/addressbook fg

To run it as a demon process start using:

$ bin/addressbook start

To stop the demon process call:

$ bin/addressbook stop

The default URL is to access the application is:

http://127.0.0.1:8080

To log-in at this URL you need a username and password.

• If you installed via package installation you had to chose them when running install.py. They are stored in admin.zcml.

• If you installed the sources you find username and password in dev_admin_user.zcml.

Create a new address book using the add address book link on the right. How to create new users inside this address book is described in Create new users.

Change configuration of the installation

This section is only valid if you chose package installation.

The values you entered during installation resp. update are stored in a file named install.user.ini in the address book directory.

To change the configuration values call install.py using python and enter a . as parameter like this:

$ python2.6 install.py .

The configuration questions get presented to you with your previously entered values as default.

To remove additional packages you have to edit the [package] section of install.user.ini. There is currently no other way for removal.

To remove the user name which should own the process you have to edit the [server] section of install.user.ini. Remove the value from the user line.

User management

Roles

Access to the address book is only granted after authentication. There are three roles to authorize a user:

• visitor: visit all person’s data, search and export, change own password

• editor: permissions of visitor + edit all person’s data, change own log-in name

• administrator: permissions of editor + create and change address book and users

Create new users

Users are persons from the address book augmented by log-in information.

To create the first new user inside an address book the adminstrator (who was created in First installation) has to log-in and then do the following:

1. create a new person with an e-mail address using Add person.

2. create a new user using Master data –> Users –> Add user.

The newly created user has now a log-in (e-mail address) for the address book the person belonges to.

To do

Next major version

• Probably: Full text search.

Longer term

The following features might be implemented over the next months:

• person data

  • store picture per person

• company as entity

• import

  • vCard

  • SQLite (Apple’s Addressbook.app)

• export

  • custom XLS export

  • LDAP export

• more search abilities

  • full text search

  • combined search

  • wildcard search

Change log

1.10.1 (2013-06-25)

• Update bootstrap.py to current version so updating an older instance does not fail.

1.10.0 (2013-06-21)

Features

• Added welcome page displayed after login. So additional packages might provide roles which do not allow to access the persons in the address book.

• Added ability in user preferences to set current time zone. Datetimes, e. g. creation date, modification date and user defined fields of type datetime, are converted to the selected time zone. Default is UTC.

• Added JavaScript calendar widget to datetime fields.

• Added number of displayed persons in search result handler which displays the names of the selected persons (new in 1.9.0).

• Now displays the name of the address book in HTML title tag and as headline inside the application.

• Moved link to edit form of address book from tabs to master data.

• Added checkbox in search result table to deselect all entries.

Other

• Moved source code to: https://bitbucket.org/icemac/icemac.addressbook

• Updated to run on Zope Toolkit 1.1.5.

• Updated most other packages (outside ZTK) needed for address book to newest versions.

• Simplified and streamlined test layers.

1.9.0 (2012-12-29)

Features

• Added search result handler which prints the names of the selected persons als comma separated list.

Bugfixes

• Login in a virtual hosting environment might have led to not accessible URLs. This was fixed by using the whole URL in the camefrom parameter.

Other

• Updated to Zope Toolkit 1.1.4 for dependent packages.

• Updated other dependent packages (outside ZTK) to newest versions.

• Moved chameleon-cache into var directory.

1.8.1 (2012-04-20)

Features

• Added favicon.ico to the application.

• Split preferences into multiple groups.

Bugfixes

• The search result handler which updates data did not update the catalog, so these changes were invisible for the search. Updated catalog and search result handler.

• User preferences were stored globally instead of locally in the address book of the user. Users with the same internal ID shared preferences across address books. As the internal IDs are simply a counter this happened every time if using the multi-client capability.

  The problem was fixed by storing user preferences locally and copying existing global preferences over to the each address book where a user for the internal user ID of the preferences exists.

Other

• Updated other dependent packages (outside ZTK) to newest versions.

• Using Fanstatic – a WSGI middleware – to deliver CSS and JS instead of hurry.resource.

1.8.0 (2011-12-14)

Features

• Added search result handler which allows to send an e-mail to the persons found by the search.

Bugfixes

• The search result handler which updates data did not handle keywords well, it was not possible to remove a keyword from a person using that handler.

Other

• Added some Screenshots to the SourceForge page.

• Using Chameleon 2 as HTML render engine resulting in faster page rendering. (Test run in half of the time now.)

• Updated to Zope Toolkit 1.1.3 for dependent packages.

• Updated other dependent packages (outside ZTK) to newest versions.

• Dropped some package dependencies which only existed for compatibility reasons with older versions. Data gets converted during first start-up.

Previous Versions

See OLD_CHANGES.rst inside the package.

Download