Mark Lavin avatar Mark Lavin committed ae77471

Initial documentation/release notes on lookup decorators. Fixes #44.

Comments (0)

Files changed (2)

 
         registry.register(UserLookup)
 
+
+.. versionadded:: 0.5
+
+.. _LookupDecorators
+
+Lookup Decorators
+--------------------------------------
+
+Registering lookups with django-selectable creates a small API for searching the
+lookup data. While the amount of visible data is small there are times when you want
+to restrict the set of requests which can view the data. For this purpose there are
+lookup decorators. To use them you simply decorate your lookup class.
+
+    .. code-block:: python
+
+        from django.contrib.auth.models import User
+        from selectable.base import ModelLookup
+        from selectable.decorators import login_required
+        from selectable.registry import registry
+
+
+        @login_required
+        class UserLookup(ModelLookup):
+            model = User
+            search_fields = ('username__icontains', )
+            filters = {'is_active': True, }
+
+        registry.register(UserLookup)
+
+.. note::
+
+    The class decorator syntax was introduced in Python 2.6. If you are using
+    django-selectable with Python 2.5 you can still make use of these decorators
+    by applying the without the decorator syntax.
+
+    .. code-block:: python
+
+        class UserLookup(ModelLookup):
+            model = User
+            search_fields = ('username__icontains', )
+            filters = {'is_active': True, }
+
+        UserLookup = login_required(UserLookup)
+
+        registry.register(UserLookup)
+
+Below are the descriptions of the available lookup decorators.
+
+
+ajax_required
+______________________________________
+
+The django-selectable javascript will always request the lookup data via 
+XMLHttpRequest (AJAX) request. This decorator enforces that the lookup can only
+be accessed in this way. If the request is not an AJAX request then it will return
+a 400 Bad Request response.
+
+
+login_required
+______________________________________
+
+This decorator requires the user to be authenticated via ``request.user.is_authenticated``.
+If the user is not authenticated this will return a 401 Unauthorized response.
+``request.user`` is set by the ``django.contrib.auth.middleware.AuthenticationMiddleware``
+which is required for this decorator to work. This middleware is enabled by default.
+
+staff_member_required
+______________________________________
+
+This decorator builds from ``login_required`` and in addition requires that
+``request.user.is_staff`` is ``True``. If the user is not authenticatated this will
+continue to return at 401 response. If the user is authenticated but not a staff member
+then this will return a 403 Forbidden response.

docs/releases.rst

 _________________
 
 - Template tag to add necessary jQuery and jQuery UI libraries. Thanks to Rick Testore.
+- :ref:`Lookup decorators <LookupDecorators>` for requiring user authentication or staff access to use the lookup .
 
 Backwards Incompatible Changes
 ________________________________
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.