
=====
Usage
=====

Basic usage
===========

Integrating announcements is very simple. announcements provides to you a
context processor to get template global access::

    TEMPLATE_CONTEXT_PROCESSORS = (
        # ...
        "announcements.context_processors.site_wide_announcements",
        # ...
    )

Once that is hooked up you now have access ``{{ site_wide_announcements }}``
which is a simple queryset that has filtered the announcements to give you
just the right ones. If the user viewing the page is authenticated it will
additionally pull out announcements that have been marked ``for_members``.

Here is a quick snippet of how this can be used in a template. Typically in
a base template like ``base.html`` or some sort::

    {% if site_wide_announcements %}
        <div id="site_wide_announcements">
            <ul>
                {% for announcement in site_wide_announcements %}
                <li>
                    <a href="{{ announcement.get_absolute_url }}">{{ announcement }}</a> -
                    <a href="{% url announcement_hide announcement.pk %}?next={{ request.path }}">Hide announcement</a>
                </li>
                {% endfor %}
            </ul>
        </div>
    {% endif %}
    
The above template sample uses the views discussed a little bit later on.

To give a bit of internals, the ``site_wide_announcements`` context processor
is simply a wrapper around ``current_announcements_for_request`` which is
located in ``announcements.models``.

Announcement model
------------------

To store announcements in the database, announcements comes with a model that
deals with this. It contains these fields:

 * ``title`` - The title of the announcement. This is limited to 50 characters.
   The title is completely optional since some types of annoucements don't
   really need one.
 * ``content`` - The main content of the announcement.
 * ``creator`` - The user who created the announcement.
 * ``creation_date`` - A ``DateTimeField`` indicating when the announcement
   was created.
 * ``site_wide`` - A boolean value indicating whether the announcment should
   be site-wide and used in the context processor.
 * ``members_only`` - This will tag an announcemnt as for member eyes only.

Additional uses
===============

There are a couple of ways that announcements can be used outside of its basic
usage described above.

E-mailing users
---------------

When you are creating a new announcement via the admin interface you are given
the option to send now. What this means is that announcements has optional
support of django-notification. If it is available it can send a notification
of the announcement. This then in turn can be e-mail to the user.

.. note::

    Due to the possibility of large user bases, even 20+, can cause the
    sending of a notification to take a bit of time. This could in turn cause
    the request to time out. To avoid that announcements uses the queuing
    feature of notifications. To send out the notifications you will need to
    use the ``emit_notices`` management command notifications provides.

URLconf, views and templates
----------------------------

announcements comes with three pre-defined URLs. They enable you the ability
to list, view and hide announcements. You can hook up these views very
simply in your ``urls.py``::
    
    # example urls.py.
    from django.conf.urls.defaults import *
    
    urlpatterns = patterns("",
        # ...
        url(r"^announcements/", include("announcements.urls")),
        # ...
    )

``announcement_home``
~~~~~~~~~~~~~~~~~~~~~

View: ``announcements.views.announcement_list``

It uses ``current_announcements_for_request`` to get a queryset of
announcements appropriate to the ``HttpRequest``.

``announcement_detail``
~~~~~~~~~~~~~~~~~~~~~~~

View: ``django.views.generic.list_detail.object_detail``

Displays a single announcement. Reference the Django object_detail_
documentation for more information.

.. _object_detail: http://docs.djangoproject.com/en/dev/ref/generic-views/#django-views-generic-list-detail-object-detail

``announcement_hide``
~~~~~~~~~~~~~~~~~~~~~

View: ``announcements.views.announcement_hide``

This view will mark a given announcement as hidden and redirect the user
to the provide ``next`` ``GET`` argument.
