=====
Usage
=====

Integrating notification support into your app is a simple three-step process.

  * create your notice types
  * create your notice templates
  * send notifications

Creating Notice Types
=====================

You need to call ``create_notice_type(label, display, description)`` once to
create the notice types for your application in the database. ``label`` is just
the internal shortname that will be used for the type, ``display`` is what the
user will see as the name of the notification type and `description` is a
short description.

For example::

    notification.create_notice_type("friends_invite", "Invitation Received", "you have received an invitation")

One good way to automatically do this notice type creation is in a
``management.py`` file for your app, attached to the syncdb signal.
Here is an example::

    from django.db.models import signals

    try:
        from notification import models as notification
    
        def create_notice_types(app, created_models, verbosity, **kwargs):
            notification.create_notice_type("friends_invite", "Invitation Received", "you have received an invitation")
            notification.create_notice_type("friends_accept", "Acceptance Received", "an invitation you sent has been accepted")
    
        signals.post_syncdb.connect(create_notice_types, sender=notification)
    except ImportError:
        print "Skipping creation of NoticeTypes as notification app not found"

Notice that the code is wrapped in a try clause so if django-notification is
not installed, your app will proceed anyway.


Notification templates
======================

There are four different templates that can to be written for the actual content of the notices:

  * ``short.txt`` is a very short, text-only version of the notice (suitable for things like email subjects)
  * ``full.txt`` is a longer, text-only version of the notice (suitable for things like email bodies)
  * ``notice.html`` is a short, html version of the notice, displayed in a user's notice list on the website
  * ``full.html`` is a long, html version of the notice (not currently used for anything)

Each of these should be put in a directory on the template path called ``notification/<notice_type_label>/<template_name>``.
If any of these are missing, a default would be used. In practice, ``notice.html`` and ``full.txt`` should be provided at a minimum.

For example, ``notification/friends_invite/notice.html`` might contain::
    
    {% load i18n %}{% url invitations as invitation_page %}{% url profile_detail username=invitation.from_user.username as user_url %}
    {% blocktrans with invitation.from_user as invitation_from_user %}<a href="{{ user_url }}">{{ invitation_from_user }}</a> has requested to add you as a friend (see <a href="{{ invitation_page }}">invitations</a>){% endblocktrans %}

and ``notification/friends_full.txt`` might contain::
    
    {% load i18n %}{% url invitations as invitation_page %}{% blocktrans with invitation.from_user as invitation_from_user %}{{ invitation_from_user }} has requested to add you as a friend. You can accept their invitation at:
    
    http://{{ current_site }}{{ invitation_page }}
    {% endblocktrans %}

The context variables are provided when sending the notification.


Sending Notification
====================

There are two different ways of sending out notifications. We have support
for blocking and non-blocking methods of sending notifications. The most
simple way to send out a notification, for example::

    notification.send([to_user], "friends_invite", {"from_user": from_user})

One thing to note is that ``send`` is a proxy around either ``send_now`` or
``queue``. They all have the same signature::

    send(users, label, extra_context, on_site)

The parameters are:

 * ``users`` is an iterable of ``User`` objects to send the notification to.
 * ``label`` is the label you used in the previous step to identify the notice
   type.
 * ``extra_content`` is a dictionary to add custom context entries to the
   template used to render to notification. This is optional.
 * ``on_site`` is a boolean flag to determine whether an ``Notice`` object is
   created in the database.

``send_now`` vs. ``queue`` vs. ``send``
---------------------------------------

Lets first break down what each does.

``send_now``
~~~~~~~~~~~~

This is a blocking call that will check each user for elgibility of the
notice and actually peform the send.

``queue``
~~~~~~~~~

This is a non-blocking call that will queue the call to ``send_now`` to
be executed at a later time. To later execute the call you need to use
the ``emit_notices`` management command.

``send``
~~~~~~~~

A proxy around ``send_now`` and ``queue``. It gets its behavior from a global
setting named ``NOTIFICATION_QUEUE_ALL``. By default it is ``False``. This
setting is meant to help control whether you want to queue any call to
``send``.

``send`` also accepts ``now`` and ``queue`` keyword arguments. By default
each option is set to ``False`` to honor the global setting which is ``False``.
This enables you to override on a per call basis whether it should call
``send_now`` or ``queue``.

Optional notification support
-----------------------------

To allow your app to still function without notification, you can wrap your
import in a try clause and test that the module has been loaded before sending
a notice.

For example::

    try:
        from notification import models as notification
    except ImportError:
        notification = None

and then, later:

    if notification:
        notification.send([to_user], "friends_invite", {"from_user": from_user})