.. _topics-install:

===========================================
How to install Softwarefabrica Django Forms
===========================================

.. admonition:: About this document

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

.. contents::
   :depth: 3

.. _pre-requisites:

See also the `documentation index`_.

.. _`documentation index`: index.html

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

This library depends on `softwarefabrica.django.utils`_ 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.forms

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

If you are using Ubuntu, to install system-wide:

::

  $ sudo easy_install softwarefabrica.django.forms

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

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

Then from the ``softwarefabrica.django.forms`` 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.forms
.. _`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-forms sf-forms

3. Then from the ``sf-forms`` 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::

    $ 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.forms import version
    >>> version.VERSION
    (0, 9, 'dev')
    >>> version.get_version()
    u'0.9-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-forms`` 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-forms
.. _`bugs`: https://bugs.launchpad.net/sf-django-forms
.. _`LaunchPad`: http://launchpad.net
.. _`Bazaar`: http://bazaar-vcs.org/
.. _`changes`: http://bazaar.launchpad.net/~softwarefabrica/sf-django-forms/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 app 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'``)::

    INSTALLED_APPS = (
        ...
        'softwarefabrica.django.utils',
        'softwarefabrica.django.forms',
    )

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 provided ``jscalendar-1.0.zip`` Javascript calendar 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 `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>

Since there are no associated models, a ``manage.py syncdb`` command is not
necessary.

That's it!

.. _`modules documentation`: modules.html
