.. _usage:

=======================
Basic Usage of Birdland
=======================


This document provides an overview of the basic setup of a Birdland blog in
a Django_ project.


Basic Settings
==============

Before installing Birdland's models, it should be noted that in order to make
use of the `django-tagging`_ ``TagField``, a working copy of
`django-tagging`_ must be installed, and must be present in your project's
``INSTALLED_APPS`` setting.

If you don't wish to make use of the tagging features of Birdland, but use
`django-tagging`_ elsewhere in your project, you must specify
``BIRDLAND_TAGGING_ENABLED = False`` in your project's settings.


Installing Birdland Models
==========================

Before installing Birdland's models in your project, make sure you have added
Django's auth_ app to your ``INSTALLED_APPS`` as Birdland relies upon its
``User`` model to link posts with authors. To install and use Birdland's models
in your project, add ``'birdland'`` to your ``INSTALLED_APPS`` setting and run::

    $ manage.py syncdb

from the command line in your project's directory.


Including Birdland URLs
=======================

Birdland ships with a default ``URLConf`` which provides patterns for a latest
entries list, year, month, week and day post archive, a post authors list, and
an author archive views. It also provides RSS and Atom feed views, and if
tagging integration is enabled it provides a tags-for-posts list view pattern
and a posts-for-tag list view.

Once you have installed Birdland's models, you can wire up this default
Birdland ``URLConf`` with the prefix ``/blog/``, for example, by including the
following in your project's ``ROOT_URLCONF``::

    (r'^blog/', include('birdland.urls')),

For more information on customizing some of the default parameters these patterns
use, see the section on :ref:`settings <settings>`. If you want to write your own
patterns for Birdland's views, see the section on :ref:`Birdland's views <views>`.


Required Templates
==================

Birdland does not include a default set of templates, so it is up to you to
provide templates for any of the included views you choose to use. For information
on what these views should be named and what context is provided to them, see the
:ref:`views section <views>`.


.. _Django: http://www.djangoproject.com/
.. _django-tagging: http://code.google.com/p/django-tagging/
.. _auth: http://docs.djangoproject.com/en/dev/topics/auth/#topics-auth
