django-pusherable 0.1.0

Real time object access notifications via Pusher

=============================
django-pusherable
=============================

Real-time object access notifications via Pusher_

.. _Pusher: https://pusher.com

Installation
------------

Install django-pusherable::

pip install django-pusherable


Configuration
-------------

Then add `pusherable` to your `INSTALLED_APPS`. You will also need to add your Pusher
app credentials to `settings.py`. These are available on your app keys page.::

PUSHER_APP_ID = u""
PUSHER_KEY = u""
PUSHER_SECRET = u""

Mixins
------

To begin receiving notifications about an object use the mixins.::

from pusherable.mixins import PusherDetailMixin, PusherUpdateMixin

class PostDetail(PusherDetailMixin, DetailView):
model = Post

class PostUpdate(PusherUpdateMixin, UpdateView):
model = Post
form_class = PostUpdateForm

When the view is accessed it will send an event on the channel
`modelname_pk` which contains a JSON representation of the object (model instance)
being accessed as well as the user.

The data will be in the form:

{
"object": {
"question": "What's up?",
"pub_date": "2013-08-08T11:16:24",
"id": 1
},
"user": "admin"
}

Which fields are included and excluded within the `object` is configurable via
`pusher_include_model_fields` and `pusher_exclude_model_fields`. For example,
the following would exclude the `pub_date` from the event payload:

class PostUpdate(PusherUpdateMixin, UpdateView):
model = Post
form_class = PostUpdateForm
pusher_exclude_model_fields = 'pub_date'

Template tags
-------------

To subscribe to these events on your page you can use the templatetags.::

{% load pusherable_tags %}

{% pusherable_script %}

The `pusherable_script` tag will include the Pusher library. Place this in the
head of your page.::

{% pusherable_subscribe 'update' object %}

The `pusherable_subscribe` tag will begin subscribe you to the channel for the
object. The first argument is the type of event you want to subscribe to.
The default events are `update` and `view`.

When a new event is received it will pass event type and data to a Javascript
function called `pusherable_notify`. Create this function and use it to alert your
users to the new event. For example::

<script>
function pusherable_notify(event, data) {
alert(data.user + "has begun to " + event + " " + data.model);
}
</script>

Running Tests
-------------

Pusherable comes with test requirements and a test runner.::

pip install -r requirements-test.txt
python runtests.py


Credits
-------

django-pusherable was built by `Aaron Bassett`_ for Pusher.

.. _Aaron Bassett: https://twitter.com/aaronbassett