django-notifications-sitewide
=============================
django-notifications-sitewide allows you to show site-wide notifications to inform your users about maintenance and other important events (one at a time).
# Features
* Store as many notifications as you want, show one at a time
* The shown notification is cached, so it doesn’t use the database until the cache items expire
* If there is no active notification (which is very common), this state is cached too
* Each user can close (hide) the currently shown notification
* If you edit the notification (correct typos, etc), it remains hidden for those users who closed it
* If you create a new notification (or disable, and then enable a previously shown), then it is shown for all users (whether they hid the previous notification or not)
* The installation process is clean and easy
The notification is shown on every page until the user clicks the ×:
As soon as the user clicks ×, the notification is hidden (but an icon appears, and it allows to show the notification again):
# How it works
After you installed the reusable application (it’s called “notifications”), you can go to the admin site and add a notification. If you check the “Show on the website” checkbox, the notification is marked as active: the show_this_message field is set to True and the shown_since field is populated with the current date and time. All other notifications are updated to make certain that these fields are only set for this notification (as there cannot be more than one shown notification at a time). The same also happens if you save a previously created notification object.
Every time you save or delete a notification, the “shown_notification” key is deleted from the cache and the “shown_notification_available” cache key is set to True if there is a notification with the show_this_message set to True (otherwise the cache key is set to False).
When a user opens a page, the [context processor](https://docs.djangoproject.com/en/dev/ref/templates/api/#subclassing-context-requestcontext) checks the “shown_notification_available” cache key. If it is set to False, then it only returns None as the notification:
{'top_notification': None}
If the “shown_notification_available” cache key is not present, or is set to True, then it tries to load the notification object from the cache (using the “shown_notification” cache key).
If there is no such item in the cache, then it tries to load it from the database. If it’s not in the database either, the “shown_notification_available” cache key is set to False (so the context processor won’t try to load it from the database next time: until the cache item expires or a site administrator creates a shown notification).
If the notification is found in the database, it is written to the “shown_notification” cache key.
In case the notification is available (whereever it was loaded from), it is included into the context and the request.COOKIES dictionary is checked. If it has the “closed_notification_timestamp” and the timestamp equals to the timestamp from the shown_since field of the notification, then the context processor sets the “hide_top_notification” context variable to True. Otherwise it is set to False.
Then, if there is an active notification, it is shown on the website. If the hide_top_notification context variable is set to True, then the notification is hidden by default, but an icon is shown (and the user can click on it and the notification appears). It hide_top_notification it set to False, then the icon used to show the notification is hidden by default, but the notification itself is shown.
When the user clicks the ×, the notification is hidden (and the icon for showing it again appears), and the “closed_notification_timestamp” cookie is set to the timestamp of the shown notification (taken from the “timestamp” data attribute of the div tag that contains the notification).
# Installation
#### Step 1
Clone this repository:
git clone git://github.com/aruseni/django-notifications-sitewide.git
#### Step 2
Put the “notifications” reusable application somewhere on your PYTHONPATH (e.g. in your project directory).
#### Step 3
Open settings.py for your project.
#### Step 4
Add the application to INSTALLED_APPS:
INSTALLED_APPS = (
…
'notifications',
…
)
#### Step 5
Add the context processor:
TEMPLATE_CONTEXT_PROCESSORS = (
…
"notifications.context_processors.notification_processor",
…
)
**Note**: if you didn’t add any context processors before (you don’t have TEMPLATE_CONTEXT_PROCESSORS in your settings.py), make sure to also [specify the default ones](https://docs.djangoproject.com/en/1.1/ref/settings/#template-context-processors) so they continue to work.
#### Step 6
Create the table in the database:
python manage.py syncdb
You should see something like this:
Creating tables ...
Creating table notifications_notification
Installing custom SQL ...
Installing indexes ...
Installed 0 object(s) from 0 fixture(s)
#### Step 7
Edit your base template (usually base.html).
Add this where you want the notifications to appear (most commonly, on the top):
{% if top_notification %}
{% endif %}
And add this where you want the “Show notification” link to appear (feel free to replace it by an icon or something else):
{% if top_notification %}
{% endif %}
#### Step 8
Include [jQuery](http://jquery.com/) and [notifications.js](https://github.com/aruseni/django-notifications-sitewide/blob/master/notifications.js).
Like this:
# Example
If you want to make something like what’s on the screenshots, your template will look like this (let’s simplify it as it’s only an example):
Notification test
{% load i18n %}
{% if top_notification %}