Usage

After installing and configuring it, you need to adapt your models to use knocker interface.

  • Extend your model to use KnockerModel and ModelMeta

  • Override the api if needed

  • Load {% static "js/knocker.js" %} and {% static "js/reconnecting-websocket.min.js" %} into the templates

  • Add the following code:

    <script type="text/javascript">
      var knocker_language = '{{ LANGUAGE_CODE }}';
      var knocker_url = '/notifications';  // Set this to the actual URL
    </script>
    

    The value of knocker_url must match the path configured in myproject.routing.channel_routing.py.

  • Deploy you project according to the channels documentation

Now, for every user which has of the knocker-enabled pages opened, whenever an instance of your knocker-enabled models is saved, a desktop notification is emitted.

Knocker provides a default signal which is fired whenever a model instance is saved and is registered automatically.

If you have any issue with signal firing, please open an issue.

For a complete implementation of a knocker-enabled application refer to the sample app included in knocker tests.

Knocker API

The Knocker API is a very thin layer of syntactic sugar on top of django-meta and channels.

Attributes

KnockerModel mixin defines the attribute to build the notification information:

_knocker_data = {
    'title': 'get_knocker_title',
    'message': 'get_knocker_message',
    'icon': 'get_knocker_icon',
    'url': 'get_absolute_url',
    'language': 'get_knocker_language',
}

Each key in the _knocker_data attribute is an attribute of the notification package delivered to the client. Each key can be overridden in the __init__ method or the attribute entirely redefined in the model class:

class Post(KnockerModel, ModelMeta, models.Model):
    title = models.CharField(_('Title'), max_length=255)
    ...

    _knocker_data = {
        'title': 'get_my_title',
        'message': 'get_message',
        'icon': 'get_knocker_icon',
        'url': 'get_absolute_url',
        'language': 'get_knocker_language',
    }

    def get_message(self):
        return self.title

    def get_my_title(self):
        return 'hello'

Attributes

  • title: the title that appears in the desktop notification; defaults to New Model {{ verbose name }};

  • message: the content of the desktop notification; default to the result of self.get_title on the model instance;

  • icon: an icon displayed on the notification; defaults to the value of KNOCKER_ICON_URL;

  • url: the url the notification is linked to; default to the model get_absolute_url;

  • language: the language group the notification is sent; if the model uses django-parler or django-hvad the language of the instance is determined by calling self.get_current_language(), otherwise the current django language is used.

Methods

django-knocker defines a few methods that are intended to be overridden in the models

class knocker.mixins.KnockerModel(*args, **kwargs)[source]
get_knocker_icon()[source]

Generic function to return the knock icon

Defaults to the value of settings.KNOCKER_ICON_URL

get_knocker_language()[source]

Returns the current language.

This will call selg.get_current_language if available or the Django django.utils.translation.get_language() otherwise

get_knocker_message()[source]

Generic function to return the knock message.

Defaults to calling self.get_title

get_knocker_title()[source]

Generic function to return the knock title.

Defaults to ‘new model_verbose_name

should_knock(signal_type, created=False)[source]

Generic function to tell whether a knock should be emitted.

Override this to avoid emitting knocks under specific circumstances (e.g.: if the object has just been created or update)

Parameters:
  • signal_type – type of signal between pre_save, post_save, pre_delete, post_delete

  • created – True if the object has been created