Commits

Anonymous committed 90e4c6f

  • Participants
  • Parent commits 4997404

Comments (0)

Files changed (1)

-== Welcome ==
-
-Welcome to your wiki! This is the default page we've installed for your convenience. Go ahead and edit it.
-
-=== Wiki features ===
-
-This wiki uses the [[http://www.wikicreole.org/|Creole]] syntax, and is fully compatible with the 1.0 specification.
-
-The wiki itself is actually a hg repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately.
-
-Go ahead and try:
-
-{{{
-$ hg clone http://bitbucket.org/mhall119/django-extpermswiki/
-}}}
-
-Wiki pages are normal files, with the .wiki extension. You can edit them locally, as well as creating new ones.
-
-=== Syntax highlighting ===
-
-You can also highlight snippets of text, we use the excellent [[http://www.pygments.org/|Pygments]] library.
-
-Here's an example of some Python code:
-
-{{{
-#!python
-
-def wiki_rocks(text):
-	formatter = lambda t: "funky"+t
-	return formatter(text)
-}}}
-
-You can check out the source of this page to see how that's done, and make sure to bookmark [[http://pygments.org/docs/lexers/|the vast library of Pygment lexers]], we accept the 'short name' or the 'mimetype' of anything in there.
-
-Have fun!
+**This page is a work in progress.**
+
+<<toc>>
+
+== Roles ==
+
+ExtPerms Roles lets you define what a users "role" is, relative
+to a particular instance of a model.  You can then give users in that role
+additional permissions to that particular instance.
+
+== Defining Roles ==
+
+ExtPerms Roles are defined much like ModelAdmins are defined for the //django.contrib.auth//
+module.  You must define a **roles.py** module in the base of your application.
+This file is read during a syncdb call, and will automatically add entries into
+your database for the defined roles.
+
+For each Model you want to manage through ExtPerms Roles, you must register it with a 
+RoleManager class:
+{{{
+#!python
+from extperms.auth import roles
+
+class WidgetRoles(roles.RoleManager):
+    pass
+    
+roles.register(examples.models.Widget, WidgetRoles)
+}}}
+
+=== By User ===
+
+ExtPerms provides two role types that connect a user to a Model instance, **IsSelf** and
+**UserIs**.
+
+A user has the **IsSelf** role only on instances of //django.contrib.auth.models.User//
+that represent their own user account.
+
+A user has the **UserIs** role when the specified field in the Model instance is a
+ForeignKey to their own user account, or a text field who's value matches their
+username.
+
+{{{
+#!python
+from extperms.auth import roles
+
+class WidgetRoles(roles.RoleManager):
+    supplier = roles.UserIs('supplier')
+    
+roles.register(examples.models.Widget, WidgetRoles)
+}}}
+This will give the user the 'supplier' role when their user account is the value
+of the ForeignKey //Widget.supplier//.
+
+=== By Group ===
+
+O9 also supplies the **UserIn** role type that connects a user to a Model 
+instance through the user's membership in a group associated with the Model 
+instance.
+
+{{{
+#!python
+from extperms.auth import roles
+
+class WidgetRoles(roles.RoleManager):
+    supplier = roles.UserIs('supplier')
+    dept_member = roles.UserIn('department__membership')
+        
+roles.register(examples.models.Widget, WidgetRoles)
+}}}
+This will give the user the 'dept_member' role when they are a member of the
+group specified in the Department.membership ForeignKey for the Department
+specified in the Widget.department ForeignKey.  
+
+Note how the field specified in
+the role definition can span multiple levels of ForeignKeys by separating them
+with two underscores, keeping with the convention used by Django's QuerySet.
+
+=== Custom Roles ===
+
+While these pre-defined roles will handle most role definitions you could need,
+you are by no means limited to just those.  You can create your own subclass or
+**extperms.auth.roles.RoleBase** to create the role definition you need.
+
+== Role Permissions ==
+
+Django lets you associate Permissions to Users and Groups.  ExtPerms also lets you 
+associate Permissions to named Roles.  When a user is determined to be in that
+role in relation to a particular Model instance, they will be given the additional
+permissions specified in the role.  
+
+You can do the same by getting an instance of the RoleManager defined for that 
+Model instance:
+
+{{{
+#!python
+from extperms.auth import roles
+
+widget_instance = examples.models.Widget()
+roles = roles.get_roles(widget_instance)
+}}}
+
+You can then check if the current user has a specific permission:
+{{{
+#!python
+roles.has_perm('examples.change_widget')
+}}}
+
+Or a combination of permissions:
+{{{
+#!python
+roles.has_all_perms('examples.change_widget', 'examples.modify_widget__name')
+
+roles.has_any_perm('examples.read_widget', 'examples.view_widget__name')
+}}}
+
+You can also get a list of roles, by name, that the user has in relation to that 
+Model instance:
+{{{
+#!python
+user_has = roles.getUserRoles()
+}}}