Commits

Kai Diefenbach  committed 3f8e1f1

Update docs.

  • Participants
  • Parent commits 0b4bc77

Comments (0)

Files changed (5)

File docs/index.rst

    :maxdepth: 1
    
    installation.rst
-   usage.rst
+   usage/index.rst
    api.rst
 
 Indices and tables

File docs/usage.rst

-=====
-Usage
-=====
-
-.. warning::
-
-    django-permissions is in alpha state. Please consider the API as supposed 
-    to be changed until it reaches beta state.
-
-Create a new permission
------------------------
-
-.. code-block:: python
-
-    from permissions.utils import register_permission
-    permission = register_permission("View", "view")
-
-Create a new group
-------------------
-
-.. code-block:: python
-
-    from permissions.utils import register_group
-    brights = register_group("Brights")
-    
-This will create a default Django group.
-
-Create a content object
------------------------
-
-.. code-block:: python
-
-    from django.contrib.flatpages.models import FlatPage
-    content = FlatPage.objects.create(title="Example", url="example")
-
-Grant permission
-----------------
-
-.. code-block:: python
-
-    from permission.utils import grant_permission
-    grant_permission("view", brights, content)
-
-Now all users which are member of the group "Brights" have the permission to
-view object "content". 
-
-.. note::
-
-    You can also grant permission to single users.
-
-Check permission
-----------------
-
-.. code-block:: python
-
-    from permission.utils import has_permission
-    result = has_permission("view", request.user, content)
-
-    if result == False:
-        print "Alert!"
-
-This will check whether the current user has the permission "View" for the 
-FlatPage "content".

File docs/usage/additional_groups.rst

+=================
+Additional groups
+=================
+
+.. warning::
+
+    django-permissions is in alpha state. Please consider the API as supposed
+    to be changed until it reaches beta state.
+
+This will demonstrate how one can create special groups (per convention) and
+check permissions against them even if the user has not been assigned to these
+groups explicitly.
+
+Create new permissions
+----------------------
+
+.. code-block:: python
+
+    from permissions.utils import register_permission
+    permission = register_permission("View", "view")
+    permission = register_permission("Edit", "edit")
+
+Create new groups
+------------------
+
+.. code-block:: python
+
+    from permissions.utils import register_group
+    anonymous = register_group("Anonymous")
+    owner = register_group("Owner")
+
+This will create default Django groups.
+
+Create a content object
+-----------------------
+
+.. code-block:: python
+
+    from django.contrib.flatpages.models import FlatPage
+    content = FlatPage.objects.create(title="Example", url="example")
+
+Grant permissions
+-----------------
+
+.. code-block:: python
+
+    from permission.utils import grant_permission
+    grant_permission("view", anonymous, content)
+    grant_permission("edit", owner, content)
+
+Now all users which are member of the special group "Anonymous" have the
+permission to view the object "content". And all users which are member of the
+special group "Owner" have the permission to edit the content.
+
+Check permission
+----------------
+
+.. code-block:: python
+
+    from permission.utils import has_permission
+    from permission.utils import get_group
+    
+    # Every user is automatically within the Anonymous group.
+    groups = [get_group("Anonymous")]
+    
+    # The creator of the page is also within the Owner group.
+    # Note: FlatPages actually don't have a creator attribute.
+    if request.user == content.creator:    
+        groups.append(get_group("Owner"))
+    
+    # Passing the additional groups to has_permission    
+    result = has_permission("edit", request.user, content, groups)
+
+    if result == False:
+        print "Alert!"

File docs/usage/index.rst

+Usage
+=====
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+   
+   simple.rst
+   additional_groups.rst

File docs/usage/simple.rst

+======
+Simple
+======
+
+.. warning::
+
+    django-permissions is in alpha state. Please consider the API as supposed 
+    to be changed until it reaches beta state.
+
+Create a new permission
+-----------------------
+
+.. code-block:: python
+
+    from permissions.utils import register_permission
+    permission = register_permission("View", "view")
+
+Create a new group
+------------------
+
+.. code-block:: python
+
+    from permissions.utils import register_group
+    brights = register_group("Brights")
+    
+This will create a default Django group.
+
+Create a content object
+-----------------------
+
+.. code-block:: python
+
+    from django.contrib.flatpages.models import FlatPage
+    content = FlatPage.objects.create(title="Example", url="example")
+
+Grant permission
+----------------
+
+.. code-block:: python
+
+    from permission.utils import grant_permission
+    grant_permission("view", brights, content)
+
+Now all users which are member of the group "Brights" have the permission to
+view object "content". 
+
+.. note::
+
+    You can also grant permission to single users.
+
+Check permission
+----------------
+
+.. code-block:: python
+
+    from permission.utils import has_permission
+    result = has_permission("view", request.user, content)
+
+    if result == False:
+        print "Alert!"
+
+This will check whether the current user has the permission "View" for the 
+FlatPage "content".