Author: brosner
Date: Mon Oct 20 15:39:35 2008
New Revision: 111
Added:
trunk/docs/usage.txt
Modified:
trunk/docs/index.txt
Log:
Port of documentation from the wiki. This needs to be updated.
Modified: trunk/docs/index.txt
==============================================================================
--- trunk/docs/index.txt (original)
+++ trunk/docs/index.txt Mon Oct 20 15:39:35 2008
@@ -1 +1,21 @@
-DOC PLACEHOLDER
\ No newline at end of file
+
+===================
+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
Added: trunk/docs/usage.txt
==============================================================================
--- (empty file)
+++ trunk/docs/usage.txt Mon Oct 20 15:39:35 2008
@@ -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])
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"pinax-updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/pinax-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
