Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Port of documentation from the wiki. This needs to be updated.

git-svn-id: http://django-notification.googlecode.com/svn/trunk@111 590c3fc9-4838-0410-bb95-17a0c9b37ca9
  • Loading branch information...
commit 50d43dae73ef8324cd3d61858bab13d795dc8e87 1 parent 52866b3
@brosner brosner authored
Showing with 105 additions and 1 deletion.
  1. +21 −1 docs/index.txt
  2. +84 −0 docs/usage.txt
View
22 docs/index.txt
@@ -1 +1,21 @@
-DOC PLACEHOLDER
+
+===================
+django-notification
+===================
+
+Many sites need to notify users when certain events have occurred and to allow
+configurable options as to how those notifications are to be received.
+
+The project aims to provide a Django app for this sort of functionality. This
+includes:
+
+ * Submission of notification messages by other apps.
+ * Notification messages on signing in.
+ * Notification messages via email (configurable by user).
+ * Notification messages via feed.
+
+Contents:
+
+.. toctree::
+
+ usage
View
84 docs/usage.txt
@@ -0,0 +1,84 @@
+
+=====
+Usage
+=====
+
+Integrating notification support into your app is a simple two-step process.
+
+ * create your notice types
+ * send notifications
+
+Creating Notice Types
+=====================
+
+You need to call ``create_notice_type(label, display, description)`` once to
+create the notice types for your application in the database. ``label`` is just
+the internal shortname that will be used for the type, ``display`` is what the
+user will see as the name of the notification type and `description` is a
+short description.
+
+For example::
+
+ notification.create_notice_type("friends_invite", "Invitation Received", "you have received an invitation")
+
+One good way to automatically do this notice type creation is in a
+``management.py`` file for your app, attached to the syncdb signal.
+Here is an example::
+
+ from django.db.models import signals
+
+ try:
+ from notification import models as notification
+
+ def create_notice_types(app, created_models, verbosity, **kwargs):
+ notification.create_notice_type("friends_invite", "Invitation Received", "you have received an invitation")
+ notification.create_notice_type("friends_accept", "Acceptance Received", "an invitation you sent has been accepted")
+
+ signals.post_syncdb.connect(create_notice_types, sender=notification)
+ except ImportError:
+ print "Skipping creation of NoticeTypes as notification app not found"
+
+Notice that the code is wrapped in a try clause so if django-notification is
+not installed, your app will proceed anyway.
+
+Sending Notification
+====================
+
+To send a message you use ``send(users, notice_type_label, message_template, object_list, issue_notice)``
+where ``object_list`` and ``issue_notice`` are optional.
+
+``users`` is a list of the users who should receive the notice.
+``notice_type_label`` is the label you used in the previous step to identify
+the notice type. ``message_template`` is just a string, however if ``object_list``
+is non-empty, then ``message_template`` should contain as many ``%s`` as there
+are objects in ``object_list``. These will be replaced by references to the
+corresponding objects in ``object_list``.
+
+For example::
+
+ notification.send([to_user], "friends_invite", "%s has requested to add you as a friend.", [from_user])
+
+will sent a ``friend_invite`` notice to ``to_user`` with the message
+``XXX has requested to add you as a friend.`` where XXX is a reference to the
+``from_user`` object. Depending on the notification medium, this reference may
+be a link or just plain text.
+
+``issue_notice`` is ``True`` by default but you can set it to ``False`` if you
+want a notification sent but not persisted as a ``Notice`` object in the
+database.
+
+To allow your app to still function without notification, you can wrap your
+import in a try clause and test that the module has been loaded before sending
+a notice.
+
+For example::
+
+ try:
+ from notification import models as notification
+ except ImportError:
+ notification = None
+
+and then, later:
+
+ if notification:
+ notification.send([to_user], "friends_invite", "%s has requested to add you as a friend.", [from_user])
Please sign in to comment.
Something went wrong with that request. Please try again.