Welcome to Chimère’s documentation!¶

Prerequisites¶

If you want to install the Chimère package for Debian Wheezy dependencies are managed by the package. You can go to the next section of the documentation.

• Python versions 2.6 or 2.7
• Django >= version 1.4
• South
• Postgres >= version 8.x
• Gettext
• Psycopg2
• Python Imaging Library
• Pyexiv2
• Beautiful Soup
• python-simplejson
• python-gdal
• Lxml
• Jquery version 1.7.1 or better
• Jquery-ui
• Universal Feed Parser

geodjango is a part of django since version 1.0 but it has some specific (geographically related) additional dependencies:

• geos 3.0.x
• proj.4 4.4 to 4.6
• postgis versions 1.2.1 or 1.3.x
• gdal

Optionaly (but recommanded):

• tinymce
• gpsbabel
• django-celery if you want to manage large imports

The simpliest way to obtain these packages is to get them from your favorite Linux distribution repositories. For instance on Debian Wheezy:

apt-get install python python-django python-django-south \
    postgresql-9.1 gettext python-psycopg2 python-imaging \
    python-pyexiv2 python-beautifulsoup python-simplejson python-gdal \
    python-lxml libjs-jquery libjs-jquery-ui python-feedparser \
    libgeos-3.3.3 proj-bin postgresql-9.1-postgis gdal-bin \
    tinymce gpsbabel python-django-celery javascript-common

On Debian Squeeze (you need to activate backports):

apt-get install -t squeeze-backports python-django libjs-jquery

apt-get install python python-django python-django-south \
    postgresql-8.4 gettext python-psycopg2 python-imaging \
    python-pyexiv2 python-beautifulsoup python-simplejson python-gdal \
    python-lxml libjs-jquery libjs-jquery-ui python-feedparser \
    libgeos-3.2.0 proj-bin postgresql-8.4-postgis gdal-bin \
    tinymce gpsbabel javascript-common

The package python-django-celery doesn’t exist for Debian Squeeze.

If these packages do not exist in your distribution’s repository, please refer to the applications’ websites.

Database configuration¶

Now that postgres and postgis are installed, you need to create a new user for Chimère:

su postgres
createuser --echo --adduser --createdb --encrypted --pwprompt chimere-user

Then, you have to create the database and initialize the geographic types (adapt the paths accordingly to your needs):

PG_VERSION=9.1 # 8.4 for debian Squeeze
createdb --echo --owner chimere-user --encoding UNICODE chimere "My Chimère database"
createlang plpgsql chimere # only necessary on Debian Squeeze
psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/postgis.sql
psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/spatial_ref_sys.sql

Installing the sources¶

Choose a path to install your Chimère:

INSTALL_PATH=/var/local/django
mkdir $INSTALL_PATH

# add Chimère repository
echo "deb http://debian.peacefrogs.net wheezy main" >> /etc/apt/sources.list
apt-get update
# install
apt-get install python-django-chimere

wget http://www.peacefrogs.net/download/chimere -q -O -| html2text
(...)
[[   ]] chimere-1.0.0.tar.bz2     17-Nov-2010 16:51  53K
[[   ]] chimere-1.0.1.tar.bz2     17-Nov-2010 16:51  53K
[[   ]] chimere-1.0.2.tar.bz2     17-Nov-2010 16:51  53K
(...)

wget http://www.peacefrogs.net/download/chimere/chimere-1.0.2.tar.bz2

cd $INSTALL_PATH
tar xvjf chimere-last.tar.bz2
chown -R myusername:www-data chimere

CHIMERE_LOCALNAME=mychimere
CHIMERE_BRANCH=v2.0 # choose v2.0 for stable ou master for bleeding edge
cd $INSTALL_PATH
git clone git://www.peacefrogs.net/git/chimere
cd chimere
git checkout origin/$CHIMERE_BRANCH

Creating a custom project template¶

A default project can be found on Gitorious. Get it and start a new project with it (or get another project based on Chimère):

cd $INSTALL_PATH/chimere
git clone git://gitorious.org/chimere-example-project/chimere-example-project.git
django-admin startproject --template=chimere-example-project mychimere_project
rm -rf chimere-example-project

Your project name is used for the name of the Python package of your template. As a Python package it should follow the rule of Python variable name: it must contain at least one letter and can have a string of numbers, letters and underscores (“_”) to any length. Don’t use accentuated letters. Don’t begin the name by “_” because it has special significance in Python.

In your Chimère application directory create local_settings.py to fit to your configuration. A base template is provided (local_settings.py.example) and short descriptions of the more relevant fields are given below (at least check them). Most of these settings are initialized in settings.py.

cd $INSTALL_PATH/chimere/mychimere_project
cp local_settings.py.sample local_settings.py
vim local_settings.py

Manage media path permission:

cd $INSTALL_PATH/chimere/mychimere_project
chown -R user:www-data media
chmod -R g+w media

Create log file:

mkdir /var/log/django
touch /var/log/django/chimere.log
chown -R root:www-data /var/log/django/
chmod -R g+w /var/log/django/

Regroup static files in one path:

cd $INSTALL_PATH/chimere/mychimere_project
./manage.py collectstatic

Compiling languages¶

If your language is available in the directory chimere/locale/, you will just need to get it compiled. This can be done with the following command (here, fr stands for French, replace it with the appropriate language code):

cd $INSTALL_PATH/chimere/chimere/
django-admin compilemessages -l fr

If your language is not available, feel free to create the default po file and to submit it, contributions are well appreciated. Procedure is as follows:

You first need to create the default po file (of course, replace fr according to the language you choose to create):

django-admin makemessages -l fr

There should now be a django.po file in locale/fr/LC_MESSAGES. Complete it with your translation.

Now that the translation file is completed, just compile it the same way you would have if the language file was already available.

Database initialisation¶

Create the appropriate tables (still being in your Chimère project directory):

cd $INSTALL_PATH/chimere/mychimere_project
./manage.py syncdb

You will be prompted for the creation of an administrator account (administration can be found at: http://where_is_chimere/admin/). Then you have to create tables managed with Django-South:

./manage.py migrate

The database is set, congratulations!

You can load the default group permissions (it is at least a good start):

./manage.py loaddata ../chimere/fixtures/auth_group.json

If you want to populate your installation with default data (don’t do this on an already populated instance!):

./manage.py loaddata ../chimere/fixtures/default_data.json

Webserver configuration¶

apt-get install apache2 libapache2-mod-wsgi

cp $INSTALL_PATH/chimere/apache/django.wsgi \
               $INSTALL_PATH/chimere/apache/mydjango.wsgi
vim $INSTALL_PATH/chimere/apache/mydjango.wsgi
cp $INSTALL_PATH/chimere/apache/apache-wsgi.conf \
               /etc/apache2/sites-available/chimere
vim /etc/apache2/sites-available/chimere
# create log dir
mkdir /var/log/apache2/chimere/
chown www-data /var/log/apache2/chimere/

a2ensite chimere
/etc/init.d/apache2 reload

. /etc/default/locale

Configuring the Sites framework¶

Sites framework allow you to serve the same content on different domains. Most of you will probably use only one domain but this unique domain has to be configured. This is done in the web administration interface in Sites > Sites. You only need to change example.com by your domain name. If you forget to do that, some functionalities such as RSS feeds will not work properly.

Getting new versions of dependencies¶

If you want to install the Chimère package for Debian Wheezy dependencies are managed by the package. You can go to the next section of the documentation.

apt-get install python-lxml libjs-jquery gpsbabel python-gdal

apt-get install -t squeeze-backports python-django python-django-south \
                   python-simplejson libjs-jquery-ui python-pyexiv2 \
                   python-feedparser javascript-common libjs-jquery

apt-get install python-django-south python-simplejson libjs-jquery-ui \
                python-pyexiv2 python-feedparser javascript-common

apt-get install python-django-celery python-kombu

Getting the new sources¶

To simplify further instructions, some environment variables are initialized.

CHIMERE_PATH=/srv/chimere
CHIMERE_BRANCH=v1.2        # version 1.1 -> 1.2
CHIMERE_BRANCH=v2.0        # version 1.2 -> 2.0
CHIMERE_BRANCH=master      # version 2.0 -> master
CHIMERE_LOCALNAME=mychimere

Your local name is used for the name of your local Git branch and the Python package. As a Python package it should follow the rule of Python variable name: it must be at least one letter and can have a string of numbers, letters and underscores (“_”) to any length. Don’t begin the name by “_” because it has special significance in Python.

rm -rf $CHIMERE_PATH/chimere

# add Chimère repository
echo "deb http://debian.peacefrogs.net wheezy main" >> /etc/apt/sources.list
apt-get update
# install
apt-get install python-django-chimere

cd $CHIMERE_PATH
git stash # if you have uncommited changes
git checkout origin/$CHIMERE_BRANCH -b $CHIMERE_LOCALNAME

cd $CHIMERE_PATH
cd ..
rm -rf $CHIMERE_PATH
git clone git://www.peacefrogs.net/git/chimere
cd chimere
git checkout origin/$CHIMERE_BRANCH -b $CHIMERE_LOCALNAME

CHIMERE_APP_PATH=$CHIMERE_PATH/chimere
vim $CHIMERE_APP_PATH/settings.py

JQUERY_URL = SERVER_URL + 'jquery/jquery-1.4.4.min.js'
GPSBABEL = '/usr/bin/gpsbabel'
# simplify with an error of 5 meters
GPSBABEL_OPTIONS = 'simplify,crosstrack,error=0.005k'

cd $CHIMERE_PATH
git clone git://gitorious.org/chimere-example-project/chimere-example-project.git
django-admin startproject --template=chimere-example-project mychimere_project
rm -rf chimere-example-project

cd $CHIMERE_APP_PATH
cp local_settings.py.sample local_settings.py
vim local_settings.py

mkdir /var/log/django
touch /var/log/django/chimere.log
chown www-data -R /var/log/django

cd $CHIMERE_APP_PATH
./manage.py collectstatic

cp -ra $CHIMERE_PATH/chimere/static/* $CHIMERE_APP_PATH/static/
cp -ra $CHIMERE_PATH/chimere/static/icons/* $CHIMERE_APP_PATH/media/icons/
cp -ra $CHIMERE_PATH/chimere/static/upload $CHIMERE_APP_PATH/media/
rm -rf $CHIMERE_PATH/chimere/static/icons
rm -rf $CHIMERE_PATH/chimere/static/upload

chown www-data -R $CHIMERE_APP_PATH/media/

cp $CHIMERE_PATH/example_project/settings.py $CHIMERE_LOCALNAME
./manage.py collectstatic

Migrate database¶

cd $CHIMERE_APP_PATH
python ./scripts/upgrade.py

cd $CHIMERE_APP_PATH
./manage.py syncdb --noinput
./manage.py migrate chimere 0001 --fake # fake the database initialisation
./manage.py migrate chimere

cd $CHIMERE_APP_PATH
../chimere/scripts/migrate_properties.py
# follow the instructions

cd $CHIMERE_APP_PATH
./manage.py syncdb
# les migrations ont été réinitialisées
./manage.py migrate chimere --delete-ghost-migrations --fake 0001
./manage.py migrate chimere

Update translations¶

cd $CHIMERE_APP_PATH
./manage.py compilemessages

cd $CHIMERE_PATH/chimere
django-admin compilemessages

Forcing the refresh of visitor’s web browser cache¶

Major changes in the javascript has been done between versions, many of your users could experience problems. There are many tricks to force the refresh of their cache. One of them is to change the location of statics files. To do that edit your local_settings.py and change:

STATIC_URL = '/static/'

to:

STATIC_URL = '/static-v2.0.0/'

Then change the webserver directive to point to your new path. Restart the web server to apply this changes.

Configuring the Sites framework¶

Managing areas¶

An Area is the base of your map. It defines:

• a name: a human readable label for this area,
• an associated URN (not mandatory): the name of the area as a web ressource. In practice, if the area is not the default area the URN is used at the end of the default URL to access to this area. This is not mandatory but necessary for each area that is not the default one,
• a welcome message (not mandatory): this message is displayed once a day per user arriving on the map,
• an order (to sort areas),
• an availability,
• a “default” state. The “default” area is viewed by default. Only one area can be the default: activating this state disables it on the possible other area with a default state,
• default checked categories (not mandatory),
• if categories are displayed dynamically. If dynamically is set, the end user only views categories which have items on the map section he is currently looking at,
• categories restriction (not mandatory): if no restriction is set all categories are available,
• an external CSS file (not mandatory): an URL to an external CSS file,
• restriction on the bounding box: if set to restricted, the end user can’t pan outside the defined bounding box. Due to technical reasons of OpenLayers, there is at this time no restriction on the zoom,
• a map bounding box: this is the area to display when arriving on the map. If the area is restricted it will be the bounding box that restricts the end user. Hold the control key, click and drag to draw the bounding box,
• available layers (not mandatory: OSM Mapnik is used by default): OSM Mapnik render, OSM MapQuest render, OSM Transport Map render, OSM CycleMap are available by default. You can add new custom layers (cf. Managing layers).

Areas are customizable directly on the web administration interface in Chimere > Areas.

As there is little chance that the default area should be appropriated for you, you’ll have to set at least one default area.

Adding many areas can be a mean to show your map in different flavors.

Managing users¶

If you are not the only administrator/moderator of this Chimère installation you have to create and manage account for the other users.

You can create a new superuser account with the Command Line Interface (CLI):

./manage.py createsuperuser

User password can be changed with the CLI (useful if you have forgotten your password):

./manage.py changepassword username

Users are customizable directly on the web administration interface in Auth/User.

To create a new account, simply click on the Add button near Users. Give a name and a default password (the user can change it on his own later).

Then complete the other pieces of information.

Check the case: Staff status (or this user will not be able to log to the administration website).

If this account is a new technical administrator, check Superuser status (this user must be trustworthy!). Otherwise you’ll have to give permissions to this new user. It is easier not to add permission manually but to make this user a member of a group.

Two types of default group are proposed: application administrator and moderator.

Moderator are limited to an Area (they only see items that are inside the bounding box). If a moderator manages many areas you’ll have to select many groups.

Detail of rights for default groups:

Creating property models¶

A basic installation of Chimère permits to associate a name, a category, a description, dates, multimedia files, picture files, etc. for each geographic item.

You may want to add more custom fields like phone number or opening hours. For that all you have to do is to add a new property model (Chimere/Property model).

The administration page asks you for:

• a name,
• an order (to sort properties),
• an availability to the end user (this can be used to set hidden properties),
• a mandatory status,
• the categories the property applies to (if no categories selected it applies to all),
• the type: text, long text, password or date.

To make this property available it is necessary to reload your web server (the property is cached).

All forms are then automatically updated with this new field.

If you don’t want to allow add and modification of properties you can disable this form by setting CHIMERE_HIDE_PROPERTYMODEL to True in your local_settings.py file.

Administration pages presentation¶

Administration pages are accessible at: http://where_is_your_chimere/admin/

Don’t forget the ending slash in the URL.

Identification¶

First of all, you’ll have to identify yourself with the login and password provided.

Main page¶

Once authentified you’ll have access to the main admin page.

It looks like this:

1. links to this Documentation, to the Change password form and to Log out,
2. the list of recent actions made with this account,
3. an application title, most of your action will be in the Chimere application,
4. an item inside the application. From these pages you can Add a new item or consult/Change items. The Add link leads to the new Item form. The Change link leads to the Item list. The Item list is also available by clicking on the item label.

Item list¶

1. path in the admin site. This is a convenient shortcut to come back to the main page,
2. link to create a new item from the item list,
3. search items by words (not available for all item types),
4. this filter box permits to filter current entries with some criteria (not available for all type of items),
5. the header of the table is clickable. Clicking on an header sorts the items by this header (ascending or descending). Multiple header sort is possible (the number on the right of the header explains the sorting order),
6. each item can be checked (for applying an action) or selected (by clicking on the first column) to see the detail and edit or delete it.

Item form¶

1. fields for the selected item (or blank if it is a new item) are displayed in this form. A few fields are read-only and another few are hidden. Mandatory fields have their label in bold. Changes on these fields are only effective once the form is submitted.
2. for some items there are associated sub-items. These associated items can be modified in this form. If there are many sub-items associated for the current item, they can be ordered by drag and drop.
3. the form has to be validated by one of these action buttons. They are self-explanatory.

Managing news¶

A news system is available. All you have to to do is to click on the Add button near News. For each news you have to provide a name and a content. The content can contain HTML tags. The availability is set with a checkbox.

Creating categories/subcategories¶

Before adding categories you have to set some icons. These icons appear on the map and in the categories’ box on the main map. Be careful to resize correctly your icons. Indeed the icon will be presented at their real size on the map. To add icons: the Add button near Icons.

The website http://mapicons.nicolasmollet.com/ allow to easily generate map icons.

Categories are in fact only containers for subcategories. You’ll have to provide only a name and an order. To add categories: the Add button near categories (quite clear now, isn’t it?).

Fields of subcategories are: an associated category, a name, an icon, an order, a color and an element type. These fields are mainly quite self- explanatory. The color is used to draw routes (if this subcategory contains routes). If it a basic color it can be set with the English name (for instance: red, blue, yellow or purple) otherwise you can put the HTML RVB code (for instance #9227c9). The element type is the type of element that the subcategory can contain: POI, route or both.

Editing or moderating items¶

The moderation step is quite simple. It works the same with POIs and routes. The moderator can access to all POIs (or routes) by clicking on them on the list.

A search field is available to search by name but the more interesting is to filter POIs (or route) by state and by subcategory.

There are some actions available in the action list:

• Delete: to delete selected items. A confirmation step is displayed,
• Validate: to set the status Available to selected items,
• Disable: to set the status Disabled to selected items. This is useful to keep items you don’t want to be exposed on the map,
• Managed modified items: to manage the amendment made by end users on the main site (cf. Managing end user amendment/imported item modified locally). Modified item has to be treated one by one,
• Export to...: to export selected item to the selected format.

To modify an item, classically you have to click on its name. Then you access to a form to freely modify the item.

In this form there are all data available to the end user form plus some extra fields.

• The Import fields only make sense with data imported from an external source or for data to be exported to OSM (cf. the import section of this documentation),
• Associated items fields are read-only fields that list items associated to the current one (for example the reference item of an amendment or an associated file of a route).

Associated multimedia items are at the bottom of the form. You can freely add, change items and change their order with drag and drop.

Don’t forget to validate your change with one of the Save buttons at the bottom of the form (it is easily forgotten when you change multimedia items).

If an item is not relevant the Delete button enables to remove it.

Managing end user amendment/imported item modified locally¶

Amendment can be proposed on the main site by end-users. In Chimère an amendment is a new item with the status Modified and with a link to the reference item modified.

You can also have imported items which have been modified both locally and on the external source. The new version from the external source has the status Imported and have a link to the reference item.

A special form has been developed to facilitate the processing of these modified items.

You can access to this special form with the action Managed modified items.

This form is a table with three columns:

1. The first column displays the information for the reference item,
2. The second column displays the information proposed by the submitter,
3. The third column is a list of checkboxes. For each row checked, after the validation, the value of the modified item will replace the value of the reference item.

Importing¶

In Chimère the import mechanism is based on Import object. These objects are stored in database to keep trace of imports and to facilitate the re-importation from the same source. In fact if possible the update of data from a same type of source is managed.

To add an Import object you need to go to Chimere > Imports then Add.

After that you’ll have to select your source type and then the form depends on this source type.

KML import¶

• Web address/source file (mandatory): your KML could be distant or a local file. You’ll have to fill one of the two fields.
• Filter: if you want to import only a specific Folder of your KML file put his name on this field.
• Zipped file: if your source is a KMLZ file (a zipped KML), check this case.

Shapefile import¶

• Web address/source file (mandatory): your Shapefile could be distant or a local file. You’ll have to fill one of the two fields.
• Zipped file: only zipped Shapefiles are accepted so this checkbox has to be checked.

GeoRSS import¶

Simple GeoRSS and W3C GeoRSS are managed.

• Web address (mandatory): only distant GeoRSS are managed.

CSV import¶

The format of the CSV file (number and order of columns) managed by Chimère varies depending on the properties you have added on your Chimère instance. So we recommend you to first do an export of some items in CSV with Chimère. The CSV format of the exported file will meet Chimère requirements.

By the way because of the geometry of the item this format is not very convenient to add new content but could be handy to update informations.

Warning

If you mean to update existing data by this import, unless you know how to edit WKT do not modify the geometry column.

• Web address/source file (mandatory): your CSV file could be distant or a local file. You’ll have to fill one of the two fields.

OpenStreetMap import¶

To import from OSM Chimère use the XAPI API of OSM.

• Web address (mandatory): XAPI url used to import data. This field should be filled with a default address. By default the MapQuest server is used as it seems to be the more robust. If you experience problems with OSM import, check the availability of the XAPI server used and eventually change it.
• Filter area (mandatory): draw the bounding box you want to use for your OSM import.
• Filter type (mandatory): choose if you want to import way or nodes.
• Filter tag (mandatory): choose the OSM key/value couple used to filter OSM data. A link to the OSM Map features page is provided to help you find appropriate values.
• Refresh button: this button convert your choices to appropriate XAPI args. You have to hit this button before validating the form.

./manage.py chimere_import <import_id>

Exporting¶

./manage.py chimere_export <subcategory_id> <CSV|KML|SHP> \
                           <marker|route> <filename>

Managing layers¶

There are some different layers available by default in Chimère (OSM Mapnik, OSM Mapquest, OSM Transport map, OSM Cyclemap). You can add some extra layer using the web administration pages of Chimère. The new layer is defined with the appropriate Openlayers JS code. This JS code must be a compatible Openlayers Layer instance with no ending semi-colon. For instance defining a Bing layer can be done with this kind of code:

new OpenLayers.Layer.Bing({
            name: "Aerial",
            key: "my-bing-API-key",
            type: "Aerial"})

Refer to the Openlayers documentation API for more details.

Customizing the layout and the design¶

If you only want to customize the CSS, the easiest way to do it is to add a link to an extra CSS to your Areas cf. Managing areas.

If you want to do larger changes in the layout and the style the (well named) example_project can be customized to fit your needs. Each template file present in the chimere/templates directory can be copied in your myproject/templates directory and then modified. You only need to copy files that you want to modify. These files are in Django template language mainly made of pure HTML with some logic. Refer to the Django template documentation for more details.