To enable Advanced User Permissions, begin by editing the module you wish to enable fine grained permission controls for. In the module edit screen there is a checkbox titled "Enable Advanced Permissions", check the box to reveal an area that looks like this:
As you can see, modules that employ advanced permissions need to have some form of grouping field. Some examples would be a category field if you want to give users permissions based around certain categories or an Author field if you want to give users permission to add/edit module items as a certain author. Entering the "Grouping Name" helps administrators better understand what they're giving users permission to when editing a user's permissions in the Users section.
The Main Table option is almost always your module class' table. It should be the table that you want to enforce these advanced permissions on. The Main Field option is the field in your Main Table that you want to use as a basis for permissions. The Main Field is a reference to the "id" field of an entry in another table (i.e. a categories table). You will want to setup the Other Table and Title Field to point to the table that the Main Field is a reference to and the field from that table that you wish to use as the title for that option.
Setting Advanced Permissions
After you've saved your Advanced Permissions setup for your module you should see new options when setting a normal user's permissions (Administrators and Developers have access to all modules, so they do not see these options). Below is an example of a Blog module setup to allow fine grain control over the Author field in blog posts:
As you can see, this user can now be set to have absolutely no access to certain Authors or be an Editor/Publisher of a given Author without setting "global" permissions on the entire module. The Advanced Permissions supersede the module's permission if they are higher. For example, if you set this user to be an Editor of the whole Posts module but Publisher of "Author: BigTree", they will be allowed to publish posts with the author set to BigTree. On the other hand, if you set the user to be a Publisher of the entire module, having a certain Author set to Editor or No Access will not change their permissions.
How Advanced Permissions Affect Views and Forms
When a user has advanced permissions for a module, they will only see the content for which they have editor or publisher access. This means that in a View there may be 500 items but if they are only allowed to access 5 that is all they will see. Likewise, Forms are affected similarly.
To control a user's options in a Form the field that was used for Main Field must be set to a "List" with the "Databased Populated" type. The table it uses should be the Other Table from your Advanced Permissions setup. When the user is accessing the form, they will only see the groups they are allowed access to in the dropdown. For instance, if there are 15 authors in the table but the user has editor access to one, publisher access to another, and no access to the other 13, they will only see the one they have editor access to and the one they have publisher access to. The other 13 entries will not show in the drop down.
Permissions Scenarios
- A user tries to add an option to the dropdown for a "group" they don't have access to. They will receive an Access Denied error when saving or publishing.
- A user switches the "group" of an entry they currently have publishing rights on to a "group" they only have editor rights on. The Save & Publish button will disappear and they will only be able to save a pending change.
- A user switches the "group" of an entry they currently have editor rights on to a "group" they have publishing rights on. The user still only receives the option to save a pending change.
Title Parser Function
BigTree 4.2.9 introduced the ability to parse your titles using a "Title Parser Function". This is a function that takes two parameters:
- The title field retrieved from the database
- The related ID
It should return a modified title field that will be displayed when editing user permissions. This can be useful in the event that you want to include multiple fields -- i.e. if your title field is only the first name of a person and you want to include the last name as well. You can query the related table, grab both first and last name and return the combined string.