[[TOC(inline)]]

== Introduction ==

=== What are Row Level Permissions? ===

An example of row level permissions would be: "User A has read-access to article 234" or "User D has read, write access to article 234".

=== Why do we need this? ===

An example of where this would be useful is a forum or message board. With the current permission system, a user is capable of editing all the posts or unable to edit any posts. After implementing a row level permission, it can be modified so a user is capable of editing only their own personal posts.

== Todo ==
''This is a slightly incomplete list, as of this writing my todo list is unavailable, I'll modify this when I have access to it''

 * Adding row level permission editing to admin interface - Started. I have created an application that modifies row level permissions and will be adding this to the administration interface.
 * Adding checking of row level permissions (so they actually do something)

== Using Row Level Permissions ==

=== Basic Idea ===

There are a few things you need to know about row level permissions before working with them:

 * Row level permissions use the permissions table to determine an objects possible permissions, you need to create permissions in the permissions table before using them in row level permissions.
 * Row level permissions can be negative, this is determined by an attribute called "negative". 
 * The order of checking permissions will work in the following order: User Row Level Permission -> User Model Level Permission -> Group Row Level Permission -> Group Model Level Permission. The checking will stop either at the first positive or negative, and if no permission is found will return a negative.

=== Enabling Row Level Permissions ===

Enabling row level permissions is done by using the Meta class, you enable row level permissions by setting the "row_level_permissions" attribute to true. By default, row level permissions are assumed to be disabled.

Example: To enable row level permissions for the mineral model, the model would look like:
{{{
#!python
class Mineral(models.Model):
    name = models.CharField(maxlength=150)
    hardness = models.PositiveSmallIntegerField()
    
    class Admin:
        pass
    
    class Meta:
        unique_together = (('name', 'hardness'),)
        row_level_permissions = True
  
    def __str__(self):
        return self.name
}}}

=== Accessing Row Level Permissions from a Model ===

The relation name for row level permissions from a model is "row_level_permissions", this will return all row level permissions related to the instance of the object. For example, this will return all row level permissions related to the object quartz:
{{{
#!python
...
rlp_list = quartz.row_level_permissions.all()
...
}}}

=== Accessing the Owner and Model of a Row Level Permission ===

To return the owner of a row level permission use the attribute "owner". For example:
{{{
#!python
...
user = row_level_permission.owner
...
}}}

To return the instance of a row level permission use the attribte "type". For example:
{{{
#!python
...
object = row_level_permission.type
...
}}}
''Developer's note: This will most likely change as I'm not too sure "type" accurately describes what it represents. I will update this page when I make the change.''

=== Creating a Row Level Permission ===

There are two helper methods to create row level permissions. These can be accessed by using the Row Level Permissions manager (e.g. RowLevelPermission.objects)

The first is create_row_level_permission:
{{{
#!python
def create_row_level_permission(self, object_instance, owner_instance, permission, negative=False):
   ...
}}}
The permission param can either be the codename of the permission or a permission instance. The negative param is optional and will default to false. You must pass an instance of the object and owner to this method.
''Developer's Note: I will probably add in another option to allow the permission to be an id as well.''

The second is create_default_row_permissions:
{{{
#!python
def create_default_row_level_permissions(self, object_instance, owner_instance, change=True, delete=True, negChange=False, negDel=False):
   ...
}}}
This will set up a row level permission with the default permissions set up for an object. The default permissions are: add, change and delete. An example of it's use is:
{{{
#!python
...
RowLevelPermissions.objects.create_default_row_level_permissions(quartz, user, delete=False)
...
}}}

=== Checking Permissions ===

This will be integrated into the GenericAuthorization SoC project. More info to come.

== Implementation Notes ==

Please see RowLevelPermissionsDeveloper for more information on how row level permissions are implemented.

== Download ==

Row Level Permissions are currently hosted in a branch on Django SVN. Please use: ''svn co http://code.djangoproject.com/svn/django/branches/per-object-permissions'' to download the current code. As of July 13, the subversion repository has not been updated. I will be doing this tomorrow once I finish testing my latest changes and additions. 

'''Ignore the attached files as these are old versions of the row level permissions.'''