django-notifications-hq 0.6.1

Django Notifications Documentation

django-notifications is a GitHub notification alike app for Django, it was derived from django-activity-stream

Notifications are actually actions events, which are categorized by four main components.

• Actor. The object that performed the activity.

• Verb. The verb phrase that identifies the action of the activity.

• Action Object. (Optional) The object linked to the action itself.

• Target. (Optional) The object to which the activity was performed.

Actor, Action Object and Target are GenericForeignKeys to any arbitrary Django object. An action is a description of an action that was performed (Verb) at some instant in time by some Actor on some optional Target that results in an Action Object getting created/updated/deleted.

For example: justquick (actor) closed (verb) issue 2 (object) on activity-stream (target) 12 hours ago

Nomenclature of this specification is based on the Activity Streams Spec: http://activitystrea.ms/specs/atom/1.0/

Installation

Installation is easy using pip and will install all required libraries.

$ pip install django-notifications-hq

or get it from source

$ git clone https://github.com/brantyoung/django-notifications
$ cd django-notifications
$ python setup.py install

Note that django-model-utils will be installed: this is required for the pass-through QuerySet manager.

Then to add the Django Notifications to your project add the app notifications to your INSTALLED_APPS and urlconf.

The app should go somewhere after all the apps that are going to be generating notifications like django.contrib.auth:

INSTALLED_APPS = (
    'django.contrib.auth',
    ...
    'notifications',
    ...
)

Add the notifications urls to your urlconf:

import notifications

urlpatterns = patterns('',
    ...
    url('^inbox/notifications/', include(notifications.urls)),
    ...
)

The method of installing these urls, importing rather than using 'notifications.urls', is required to ensure that the urls are installed in the notifications namespace.

How to migrate schema to 0.5.5

1. Install latest version django-south

2. Execute manage.py migrate notifications --fake 0001 command to initiate django-notifications migrate history

3. Execute manage.py migrate notifications to migrate django-notifications schema

Generating Notifications

Generating notifications is probably best done in a separate signal.

from django.db.models.signals import post_save
from notifications import notify
from myapp.models import MyModel

def my_handler(sender, instance, created, **kwargs):
    notify.send(instance, verb='was saved')

post_save.connect(my_handler, sender=MyModel)

To generate an notification anywhere in your code, simply import the notify signal and send it with your actor, recipient, verb, and target.

from notifications import notify

notify.send(user, recipient=user, verb='you reached level 10')

notify.send(comment.user, recipient=user, verb=u'replied', action_object=comment,
            description=comment.comment, target=comment.content_object)

notify.send(follow_instance.user, recipient=follow_instance.follow_object, verb=u'has followed you',
            action_object=instance, description=u'', target=follow_instance.follow_object)

API

Notification.objects.unread()

user = User.objects.get(pk=pk)
user.notifications.unread()

{% notifications_unread %}

{% notifications_unread as unread_count %}
...
{% if unread_count %}
    You have <strong>{{ unread_count }}</strong> unread notifications.
{% endif %}