Usage¶
After installing and configuring it, you need to adapt your models to use knocker
interface.
Extend your model to use
KnockerModel
andModelMeta
Override the api if needed
Load
{% static "js/knocker.js" %}
and{% static "js/reconnecting-websocket.min.js" %}
into the templatesAdd 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 inmyproject.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 Djangodjango.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