=================
End user manual
=================

This page show how to use PluggableApp in a django project.

If you need to write a django application see :doc:`pluggableapp`

Description
===========

DjangoPluggableApp allow you to add django applications to your project without
having to take care of what settings are needed by the application. All
pluggable applications register them urls, middlewares, template directories,
template contexts, etc.

Project template
================

DjangoPluggableApp came with a project template with all requirements sets. To create a project use::

  $ paster create -t django_project your_project_name

Configuration
=============

setting.py
-----------

Add this at the bottom of your settings file:

.. literalinclude:: django-myapp/test_project/settings.py
   :start-after: PLUGGABLE_APPS

There is already a set of applications available. See :ref:`available_apps`

If you specify a ``DJANGO_SETTINGS_DUMP`` then settings are dumped to avoid
time lost at reading entry_points for each application startup. The dump is
refreshed when your settings.py change.

urls.py
-------

Start your urlpatterns with those registered via pluggableapps:

.. literalinclude:: django-myapp/test_project/urls.py

Overriding default parameters
-----------------------------

You can change the url prefix defined in the pluggable app. In setting.py:

.. sourcecode:: py

  PLUGGABLE_APPS = (
      dict(name='admin', url_prefix=r'^administration/'),
      dict(name='myapp', url_prefix=r'^'),
  )

Then check that everything is ok with the command line tool::

  $ ./bin/django-pluggableapp -i
  Installed apps
  ==============
  - admin: django.contrib.admin from Django 1.2
  - myapp: myapp from django-myapp 0.1

  Generated urls
  ==============
  - ^administration/: ('', '^administration/', 'django.contrib.admin.site.urls')
  - ^: ('', '^', 'myapp.urls')
    
You can also skip the url configuration:

.. sourcecode:: py

  PLUGGABLE_APPS = (
      dict(name='admin', url_prefix=None),
      dict(name='myapp', url_prefix=r'^'),
  )

This will generate the following urls::

  $ ./bin/django-pluggableapp -i
  Installed apps
  ==============
  - admin: django.contrib.admin from Django 1.2
  - myapp: myapp from django-myapp 0.1

  Generated urls
  ==============
  - ^: ('', '^', 'myapp.urls')


Command line tools
===================

.. _available_apps:

List all available apps
------------------------

::

  $ django-pluggableapp -l
  Available apps
  ==============
  - admin: django.contrib.admin from Django 1.2
     ^admin/: ('', '^admin/', 'django.contrib.admin.site.urls')
  - admin_docs: django.contrib.admindocs from Django 1.2
     ^admin/doc/: ('', '^admin/doc/', 'django.contrib.admindocs.urls')
  - myapp: myapp from django-myapp 0.1
     ^myapp/: ('', '^myapp/', 'myapp.urls')
  - pluggable_attachments: attachments from django-attachments (not installed)
     ^attachments/: ('', '^attachments/', 'attachments.urls')
  - pluggable_messages: messages from django-messages (not installed)
     ^messages/: ('', '^messages/', 'messages.urls')
  - pluggable_pagination: pagination from django-pagination (not installed)
  - pluggable_registration: registration from django-registration (not installed)
     ^accounts/: ('', '^accounts/', 'registration.urls')
  - pluggable_reversion: reversion from django-reversion (not installed)
  - pluggable_thumbnails: easy_thumbnails from easy-thumbnails (not installed)
  
``pluggable_name`` mean that the entry_point is available in PluggableApp
itself. This mean that you need to install ``django-name`` in your python
environment by yourself.

List installed apps
-------------------

::

  $ ./bin/django-pluggableapp -i
  Installed apps
  ==============
  - admin: django.contrib.admin from Django 1.2
  - myapp: myapp from django-myapp 0.1

  Generated urls
  ==============
  - ^myapp/: ('', '^myapp/', 'myapp.urls')
  - ^admin/: ('', '^admin/', 'django.contrib.admin.site.urls')
  
Other commands
---------------

See help::

  $ django-pluggableapp -h
  Usage: django-pluggableapp [options]

  Options:
    -h, --help            show this help message and exit
    -l, --list-apps       
    -i, --installed-apps  
    -u, --print-urls      
    -p, --print-settings