From 34018c9a84da5d9db4176e19c24113b1080959be Mon Sep 17 00:00:00 2001
From: Patrick Altman <paltman@gmail.com>
Date: Tue, 3 Mar 2015 22:34:47 -0600
Subject: [PATCH] Add some docs on scoping notifications

---
 docs/index.md    | 12 ++++++++-
 docs/scoping.md  | 67 ++++++++++++++++++++++++++++++++++++++++++++++++
 docs/settings.md | 18 +++++++++++--
 mkdocs.yml       |  3 +++
 4 files changed, 97 insertions(+), 3 deletions(-)
 create mode 100644 docs/scoping.md

diff --git a/docs/index.md b/docs/index.md
index 588900aa..19ef1e1c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,6 +10,7 @@ includes:
 * Notification messages on signing in
 * Notification messages via email (configurable by user)
 * Ability to supply your own backends notification channels
+* Ability to scope notifications at the site level
 
 
 !!! note "Originally django-notification"
@@ -30,7 +31,7 @@ includes:
 
 ## Quickstart
 
-Install the development version:
+Install the latest version:
 
     pip install pinax-notifications
 
@@ -45,3 +46,12 @@ Add `pinax-notifications` to your `INSTALLED_APPS` setting:
 Add entry to your `urls.py`:
 
     url(r"^notifications/", include("pinax.notifications.urls"))
+
+Create one or more notice types:
+
+    NoticeType.create(label, display, description)
+
+In your code, send events;
+
+    from pinax.notifications.models import send
+    send([users], "label", {"extra": context})
diff --git a/docs/scoping.md b/docs/scoping.md
new file mode 100644
index 00000000..80e88538
--- /dev/null
+++ b/docs/scoping.md
@@ -0,0 +1,67 @@
+# Scoping Notifications
+
+Sometimes you have a site that has groups or teams. Perhaps you are using
+[pinax-teams](https://github.com/pinax/pinax-teams/). If this is the case you
+likely want users who might be members of multiple teams to be able to set
+their notification preferences on a per team or group basis.
+
+You will need to:
+
+* Create a custom model for settings
+* Override NoticeSettingsView
+
+
+## Custom Model for Settings
+
+First thing you need to do is subclass `pinax.notifications.models.NoticeSettingBase`
+and add whatever attributes needed to provide the scoping. For example, to
+scope by a `pinax-teams` team:
+
+    # models.py
+    from pinax.notifications.models import NoticeSettingsBase
+    
+    class TeamNoticeSetting(NoticeSettingsBase):
+        team = models.ForeignKey(Team, null=True)
+        
+        @classmethod
+        def get_lookup_kwargs(cls, user, notice_type, medium, scoping):
+            return {
+                "user": user,
+                "notice_type": notice_type,
+                "medium": medium,
+                "team": scoping
+            }
+    
+    # settings.py
+    PINAX_NOTIFICATIONS_SETTING_MODEL = "mysite.TeamNoticeSetting"
+
+
+## Override NoticeSettingsView
+
+Next, let's override the method on `pinax.notifications.views.NoticeSettingsView`
+that handles the lookup of the `setting` for each notice type and channel.
+
+    # views.py
+    from pinax.notifications.views import NoticeSettingsView
+    
+    class TeamNoticeSettingsView(NoticeSettingsView):
+        
+        def setting_for_user(self, notice_type, medium_id):
+            return self.SettingModel.for_user(
+                self.request.user,
+                notice_type,
+                medium_id,
+                scoping=self.request.team
+            )
+
+    # urls.py
+    from django.conf.urls import patterns, url
+    
+    from .views import TeamNoticeSettingsView
+    
+    
+    urlpatterns = patterns(
+        "",
+        ...
+        url(r"^notifications/settings/$", TeamNoticeSettingsView.as_view(), name="notification_notice_settings"),
+    )
diff --git a/docs/settings.md b/docs/settings.md
index 1c709549..90586311 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -30,7 +30,7 @@ file. A common use-case for overriding this default might be `https` for use on
 more secure projects.
 
 
-## PINAX_NOTIFICATIONS_LANGUAGE_MODULE
+## PINAX_NOTIFICATIONS_LANGUAGE_MODEL
 
 Formerly, this setting was `NOTIFICATION_LANGUAGE_MODULE`
 
@@ -49,7 +49,7 @@ Example model in a `languages` app::
 
 Setting this value in `settings.py`::
 
-    PINAX_NOTIFICATIONS_LANGUAGE_MODULE = "languages.Language"
+    PINAX_NOTIFICATIONS_LANGUAGE_MODEL = "languages.Language"
 
 
 DEFAULT_FROM_EMAIL
@@ -101,3 +101,17 @@ It defines how long to wait for the lock to become available. Default of -1
 means to never wait for the lock to become available. This only applies when
 using crontab setup to execute the `emit_notices` management command to send
 queued messages rather than sending immediately.
+
+
+## PINAX_NOTIFICATIONS_SETTING_MODEL
+
+This defaults to `notifications.NoticeSetting`.
+
+It exists so that you can supply your own subclass of
+`pinax.notifications.models.NoticeSettingBase` in case you needed to scope
+settings by some group or team in your site. For example, if you were using
+`pinax-teams` and wanted people to be able to set/control notifications
+differently for each team of which they were a member.
+
+See [scoping your notifications](scoping.md) for more details on how this
+works.
diff --git a/mkdocs.yml b/mkdocs.yml
index 0b5ec694..be1f2d0f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -2,6 +2,9 @@ site_name: pinax-notifications
 pages:
 - [index.md, Home]
 - [changelog.md, Change Log]
+- [usage.md, Usage]
+- [settings.md, Settings]
+- [scoping.md, Scoping Notifications]
 theme: readthedocs
 repo_url: https://github.com/pinax/pinax-notifications
 site_description: "an app"