This app is in a pre-alpha state - some assembly is required.

This Django app provides a basic integration with etherpad lite. It presently allows django users created by the django.contrib.auth app to be mapped to etherpad users and groups, the creation of pads and secure sessions.

Patches, forks, questions and suggestions are always welcome.

For now installation is all manual.

First you will need to install etherpad-lite, or have the server url and apikey of an existing etherpad-lite instance.

Lets assume if you are looking at this you already know how to install Django and start new Django projects.

You will need to clone this repo into your Django project, and add etherpadlite to the INSTALLED_APPS in your settings.py.

Set a cookie domain in your settings.py file that will be used by your django install and etherpad servers:

# Set the session cookie domain
SESSION_COOKIE_DOMAIN = '.example.com'

Finally you will need to add lines to your urls.py file. You can either add this line:

 url(r'^', include('etherpadlite.urls')),

Or, if you are already serving your home page via a different app, these lines:

 url(r'^etherpad', include('etherpadlite.urls')),
 url(r'^accounts/profile/$', include('etherpadlite.urls')),
 url(r'^logout$', include('etherpadlite.urls')),

Once you have done this, you will need to, at minimum, create a group and add a first etherpad-lite server via the django admin interface in order to take full advantage of this modules functionality:

1. Add a group: admin/auth/group/add/
2. Add an etherpad server: admin/etherpadlite/padserver/add/
3. Add an etherpad group corresponding to the auth group: admin/etherpadlite/padgroup/add/

At this point, any users you add to the django project who are members of an etherpad enabled group will be able to take full advantage of the modules features.

WARNING: This feature requires dict-style settings.DATABASES setting in your project.

django-etherpad-lite offers a management command which generates a settings.json for Etherpad-lite uses project's database configuration. It is then possible to generate a proper configuration using python manage.py generate_etherpad_settings > /path/to/etherpad/configuration/settings.json and then start Etherpad-lite using -s option: node node/server.js -s settings.json:

$ python manage.py generate_etherpad_settings
{
    "minify": true,
    "dbType": "postgres",
    "ip": "0.0.0.0",
    "maxAge": 21600000,
    "port": 9001,
    "loglevel": "INFO",
    "abiword": null,
    "defaultPadText": "",
    "dbSettings": {
        "host": "localhost",
        "password": "database_password",
        "user": "database_user",
        "database": "database_name"
    },
    "editOnly": false,
    "requireSession": false
}

This configuration can be overriden by including a ETHERPAD_CONFIGURATION setting in your settings.py. Every option corresponds to an option in the Etherpad-lite default configuration.

ETHERPAD_CONFIGURATION = {
    'port': '8088'
}

One exception is the database setting: while it's possible to override the dbType and dbSettings settings (e.g. if you prefer to use a real key-value store like Redis), for most use cases it's recommended to set the databaseAlias settings (which defaults to default) to let django-etherpad-lite extract and set database options from your project's settings:

ETHERPAD_CONFIGURATION = {
    'databaseAlias': 'nondefault',
}

django-etherpad-lite can override default pad settings with the ETHERPAD_SETTINGS settings variable. The default setting is:

ETHERPAD_SETTINGS = {
    "showControls": True,
    "showChat": True,
    "alwaysShowChat": False,
    "showLineNumbers": False,
    "useMonospaceFont": False,
    "noColors": False,
    "hideQRCode": True,
    "rtl": False,
}

If ETHERPAD_SETTINGS is defined in your settings.py, this default configuration will be overridden parameter-wise, e.g.

ETHERPAD_SETTINGS = {
    "showLineNumbers": True,
}

will keep every other setting at default value.

django-etherpad-lite defines an experimental setting, which allows overriding the user naming.

ETHERPAD_AUTHOR_NAME_MAPPER = lambda user: user.get_full_name()

ETHERPAD_AUTHOR_NAME_MAPPER defines the name that will be used to represent a Django user in Etherpad-Lite. It needs to be a callable and receives the user as its only parameter.

Per default, django-etherpad-lite works with the django.contrib.auth.models.Group model. In some circumstances, this is not desirable, e.g. when a different model is used for grouping users. For those cases, several setting exist:

ETHERPAD_GROUP_MODEL = 'mysite.myprofile.Group'
ETHERPAD_GROUP_PAD_FIELD_NAME = 'pad_group'
ETHERPAD_GROUP_USERS_FIELD_NAME = 'members'

ETHERPAD_GROUP_MODEL defines the model to be used instead of django.contrib.auth.models.Group. ETHERPAD_GROUP_PAD_FIELD_NAME is the name of the field on the custom Group model, which is usually a OneToOneField to the PadGroup model with the reverse_name property set. ETHERPAD_GROUP_USERS_FIELD_NAME is the name of the ManyToManyField field on the custom Group model, which represents the users in that group.

Some documentation exists in the github wiki.

Report issues to the issue queue.

I intend to support multiple etherpad-lite services with this App. For the moment etherpad instances must be served from the same domain name or ip address as the django app.

Copyright 2012 Sofian Benaissa.

Etherpad Lite for Django is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.