.. _topics-install:

==========================================
How to install Softwarefabrica Django Wiki
==========================================

.. admonition:: About this document

   This document describes how to install Softwarefabrica Django Wiki and use it
   in your Django applications.

.. contents::
   :depth: 3

.. _pre-requisites:

Pre-requisites
==============

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).

.. _EasyInstall: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _`softwarefabrica.django.utils`: http://pypi.python.org/pypi/softwarefabrica.django.utils
.. _`softwarefabrica.django.forms`: http://pypi.python.org/pypi/softwarefabrica.django.forms
.. _`softwarefabrica.django.crud`: http://pypi.python.org/pypi/softwarefabrica.django.crud
.. _`sflib`: http://pypi.python.org/pypi/sflib

.. _installing-official-release:

Installing an official release
==============================

Official releases are made available from PyPI_

http://pypi.python.org/pypi/softwarefabrica.django.wiki

Binary distribution
-------------------

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.

.. _EasyInstall: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _PyPI: http://pypi.python.org/pypi
.. _`distribution`: http://pypi.python.org/pypi/softwarefabrica.django.wiki

.. _`source distribution installation`:

Source distribution
-------------------

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.

.. _EasyInstall: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _PyPI: http://pypi.python.org/pypi
.. _`source distribution`: http://pypi.python.org/pypi/softwarefabrica.django.wiki
.. _`setuptools development mode`: http://peak.telecommunity.com/DevCenter/setuptools#development-mode


Windows installer
-----------------

A Windows installer will be made available in a next release.

.. _installing-development-version:

Installing the development version
==================================

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:

1. 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.)

2. Create a local branch and working tree from the official one::

    bzr branch lp:sf-django-wiki sf-wiki

3. 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

4. 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.

.. _`development home page`: https://launchpad.net/sf-django-wiki
.. _`bugs`: https://bugs.launchpad.net/sf-django-wiki
.. _`LaunchPad`: http://launchpad.net
.. _`Bazaar`: http://bazaar-vcs.org/
.. _`changes`: http://bazaar.launchpad.net/~softwarefabrica/sf-django-wiki/trunk/changes
.. _`PYTHONPATH`: http://docs.python.org/tut/node8.html#SECTION008110000000000000000
.. _`junction`: http://www.microsoft.com/technet/sysinternals/FileAndDisk/Junction.mspx
.. _`setuptools development mode`: http://peak.telecommunity.com/DevCenter/setuptools#development-mode

Using the wiki in your projects
===============================

Once you've installed the library and want to use it in your Django
projects:

1. 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',
    )

2. make sure that you have
   ``'django.template.loaders.app_directories.load_template_source'`` in your
   ``TEMPLATE_LOADERS`` setting.

3. 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',
    )

4. 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

5. 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>

6. Add a proper line in your root URLconf to point to the wiki URLs, such
   as::

     (r'wiki/', include('softwarefabrica.django.wiki.urls')),

7. Run the ``manage.py syncdb`` command::

     python manage.py syncdb

That's it!

See the `demo project`_ for a complete example.

.. _utilities:

Utilities
=========

See the `utilities guide document`_.

.. _`utilities guide document`: utilities.html

.. _`demo project`:

.. _demo-project:

Demo project
============

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`_).

.. _`jscalendar`: http://prdownloads.sourceforge.net/jscalendar/jscalendar-1.0.zip?download
.. _`softwarefabrica.django.forms`: http://pypi.python.org/pypi/softwarefabrica.django.forms
.. _`models documentation`: models.html
