About this document
This document describes how to install Softwarefabrica Django Wiki and use it in your Django applications.
This library depends on softwarefabrica.django.utils, softwarefabrica.django.forms, softwarefabrica.django.crud and sflib from the same author. If you use EasyInstall, as outlined below, dependencies will be satisfied automatically (the easy_install command will take care of everything).
Official releases are made available from PyPI
http://pypi.python.org/pypi/softwarefabrica.django.wiki
If you have EasyInstall available, you can download and install the most up-to-date version in one step. For example, on a unix-like system:
$ su # easy_install softwarefabrica.django.wiki
If you are using Ubuntu, to install system-wide:
$ sudo easy_install softwarefabrica.django.wiki
Otherwise, if EasyInstall is not available, you can just download (eg. from PyPI) the right distribution for your platform and Python version, extract it and run the usual setup.py commands:
$ su # python setup.py install
These commands will install the software in your Python installation's site-packages directory.
If you have EasyInstall available, you can download and extract the most up-to-date source distribution in one step. For example, on a unix-like system:
easy_install --editable --build-directory ~/projects softwarefabrica.django.wiki
Then from the softwarefabrica.django.wiki directory you can run the setup.py develop command to install the library in your Python site-packages directory using a link, which allows to continue developing inside the working tree without the need to re-install after every change. See the setuptools development mode documention for more information:
$ python setup.py build $ sudo # python setup.py develop
Otherwise, if EasyInstall is not available, you can just download the source distribution (eg. from PyPI), extract it and run the usual setup.py commands:
$ su # python setup.py install
This command will install the software in your Python installation's site-packages directory.
A Windows installer will be made available in a next release.
Alternatively, if you'd like to update the software occasionally to pick up the latest bug fixes and enhancements before they make it into an offical release, branch from the Bazaar repository hosted on LaunchPad instead. Just follow the procedure outlined below:
Make sure that you have Bazaar installed, and that you can run its commands from a shell. (Enter bzr help at a shell prompt to test this.)
Create a local branch and working tree from the official one:
bzr branch lp:sf-django-wiki sf-wiki
Then from the sf-wiki directory you can run the setup.py develop command to install the library in your Python site-packages directory using a link, which allows to continue developing inside the working tree without the need to re-install after every change. See the setuptools development mode documention for more information:
$ python setup.py build $ sudo # python setup.py develop
You can verify that the application is available on your PYTHONPATH by opening a Python interpreter and entering the following commands:
>>> from softwarefabrica.django.wiki import version >>> version.VERSION (1, 0, 'dev') >>> version.get_version() u'1.0-dev-BZR-rXX-panta@elasticworld.org-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
When you want to update your copy of the library source code, run the command bzr pull from within the sf-wiki directory:
bzr pull python setup.py build sudo python setup.py develop
(you need to re-run the setup.py develop command after every working tree update, to update version numbers in script wrappers).
Caution!
The development version may contain bugs which are not present in the release version and introduce backwards-incompatible changes.
If you're tracking trunk, keep an eye on the changes before you update your copy of the source code.
Once you've installed the library and want to use it in your Django projects:
put 'softwarefabrica.django.forms' in your INSTALLED_APPS setting, after its dependencies ('softwarefabrica.django.utils', 'softwarefabrica.django.forms', 'softwarefabrica.django.crud' and 'django.contrib.markup'):
INSTALLED_APPS = (
...
'django.contrib.markup',
'softwarefabrica.django.utils',
'softwarefabrica.django.forms',
'softwarefabrica.django.crud',
'softwarefabrica.django.wiki',
)
make sure that you have 'django.template.loaders.app_directories.load_template_source' in your TEMPLATE_LOADERS setting.
add 'softwarefabrica.django.utils.viewshelpers.context_vars' to your TEMPLATE_CONTEXT_PROCESSORS setting. Typically it should be:
TEMPLATE_CONTEXT_PROCESSORS = (
'django.core.context_processors.auth',
'django.core.context_processors.debug',
'django.core.context_processors.i18n',
'django.core.context_processors.media',
'django.core.context_processors.request',
'softwarefabrica.django.utils.viewshelpers.context_vars',
)
Extract the jscalendar-1.0.zip Javascript calendar provided with softwarefabrica.django.forms inside your static media javascript directory:
cd MY_PROJECT/static_media mkdir js cd js unzip ~/sf-django-forms/jscalendar-1.0.zip ln -s jscalendar-1.0 jscalendar
include the necessary Javascript bits in your base template <head>...</head> portion, as described in the softwarefabrica.django.forms modules documentation. Typically:
<head>
...
<!-- calendar -->
<link rel="stylesheet" type="text/css" href="{{ js }}/jscalendar/calendar-win2k-cold-2.css" />
<script type="text/javascript" src="{{ js }}/jscalendar/calendar.js"></script>
<!-- this is translation file - choose your language here -->
<script type="text/javascript" src="{{ js }}/jscalendar/lang/calendar-{% if request.LANGUAGE_CODE %}{{ request.LANGUAGE_CODE }}{% else %}en{% endif %}.js"></script>
<script type="text/javascript" src="{{ js }}/jscalendar/calendar-setup.js"></script>
<!-- /calendar -->
<!-- softwarefabrica.django.forms -->
<script language="javascript" type="text/javascript">
<!--
{% include "forms/js/Related.js" %}
// -->
</script>
<!-- /softwarefabrica.django.forms -->
</head>
Add a proper line in your root URLconf to point to the wiki URLs, such as:
(r'wiki/', include('softwarefabrica.django.wiki.urls')),
Run the manage.py syncdb command:
python manage.py syncdb
That's it!
See the demo project for a complete example.
See the utilities guide document.
There is a demo project included, which should give an example on how to use the wiki application. It's available in the demoproj subdirectory.
To run the development server on the demo project, enter the directory, set DJANGO_SETTINGS_MODULE, then run manage.py syncdb and manage.py runserver:
$ cd demoproj $ export DJANGO_SETTINGS_MODULE=demoproj.settings $ python manage.py syncdb $ python manage.py runserver
or just use the included setup shell script to set environment variables (it must be sourced):
$ cd demoproj $ . setup $ python manage.py syncdb $ python manage.py runserver
At this point you can already use the wiki, by visiting http://localhost:8000. But if you want to benefit from the extended calendar date and datetime fields, you have to perform one additional step. You need to go into the Javascript directory of demoproj and unzip the jscalendar DHTML calendar. You can find a copy in softwarefabrica.django.forms:
$ cd demoproj $ cd static_media/js $ unzip ~/sf-django-forms/jscalendar-1.0.zip $ mv jscalendar-1.0 jscalendar $ cd ../.. $ python manage.py syncdb $ python manage.py runserver
Then point your browser at http://localhost:8000.
The administration is at at http://localhost:8000/admin. The default administrator user is wiki, with password wiki. Don't use it on production :-)
Caution!
If you are using the demo project from an installed distribution, keep in mind that you won't be able to write to the database unless you are the user that has installed the package (usually the system administrator - root). To avoid the related run-time errors, it's recommended to run the demo project from a source distribution (see source distribution installation).