The permissions.ini file stores custom permissions and roles that can be used by an application. It is an optional file that should be placed in the application root directory (i.e. the same directory where your conf.ini, and index.php files are located).
The permissions.ini file allows you to define two things:
Permissions
Roles (i.e. sets of permissions).
Permissions and roles are used throughout Xataface to limit access to actions, records, fields, and relationships. For example, each action in your application can specify a permission that is necessary to perform the action. Your delegate classes may include getPermissions() methods to define what permissions a user gets when interacting with different records. This file (permissions.ini) simply defines the permissions that can be used by your application. It doesn't actually assign those permissions. Assigning permissions is the job of the getPermissions() (or getRoles()) method.
Defining Permissions
Permissions are defined by standalone properties in the beginning of the permissions.ini file. For example, if you were desiging a proof-reading application, you might need permissions for "submit_for_proof", or "approve_text" to correspond with the submitting a document to be proof-read, and approving a document's proof. In this case we would have the following at the beginning of our permissions.ini file:
submit_for_proof = Submit a document to be proofread
approve_text = "Approve this document's proof"
The left side of the equals sign is the name of the permission. The right side contains a human readable description of the permission and what it is for.
Limiting Access to Actions based on Permissions
At this point these permissions don't do anything. In order to be useful we need reference these permissions from an action or a section. For example, let's create an action called "submit_for_proof" which displays a form for a user to submit a document record to be proofread.
[submit_for_proof]
url="{$this->url('-action=submit_for_proof')}"
label="Submit document for proof"
category=record_actions
permission=submit_for_proof
template=submit_for_proof.html
And for completeness, since this make-believe action specifies th "submit_for_proof.html" template, we'll create the "submit_for_proof.html" template in the templates directory:
<html><body>You have permission to perform this action.</body></html>
Defining Who Get's Which Permissions
Finally, in order to benefit from permissions, your application has to decide that it is going to use permissions (unless you define a getPermissions() method, users are granted ALL permissions by default. Hence if you try to access our submit_for_proof action, we'll see it without any problem. Regardless of who we are. So let's create a simple, but restrictive getPermissions() method in our application delegate class:
<?php
class conf_ApplicationDelegate {
function getPermissions(&$record){
return Dataface_PermissionsTool::READ_ONLY();
}
}
Now if we try to access our submit_for_proof action it will give us a "Permission Denied" message, because we are only granted READ ONLY permissions (which is a role that includes the view permission and some others - but not our custom "submit_for_proof" permission.
Now we'll make a small modification to our getPermissions() method to provide us with our submit_for_proof permission:
<?php
class conf_ApplicationDelegate {
function getPermissions(&$record){
$perms = Dataface_PermissionsTool::READ_ONLY();
$perms['submit_for_proof'] = 1;
return $perms;
}
}
Now if we try to access our submit_for_proof action, it will show us our template with no error messages (hopefully).
Roles
Roles are sets of permissions. They are defined in the permissions.ini file as sections with lists of included permissions. It might be handy to create roles such as EDITOR or MANAGER which contain sets of permissions that are meant to be assigned to users of those types. For example an EDITOR may have the view and edit permissions, but not the delete permission. A MANAGER might have the view, edit, and delete permissions. You can define these two roles in the permissions.ini file as follows:
Then we could assign these roles to users using the Dataface_PermissionsTool::getRolePermissions() method:
function getPermissions(&$record){
$user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
if ( $user and $user->val('role') == 'EDITOR' ){
return Dataface_PermissionsTool::getRolePermissions('EDITOR');
} else if ( $user and $user->val('role') == 'MANAGER' ){
return Dataface_PermissionsTool::getRolePermissions('MANAGER');
}
return Dataface_PermissionsTool::READ_ONLY();
}
Or equivalently we could use the getRoles() method of our delegate class instead of getPermissions():
function getRoles(&$record){
$user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
if ( $user and $user->val('role') == 'EDITOR' ){
return 'EDITOR';
} else if ( $user and $user->val('role') == 'MANAGER' ){
return 'MANAGER'
}
return 'READ ONLY';
}
Xataface Core Permissions & Roles
Xataface is distributed with its own permissions.ini file that defines some core permissions and roles. You can look at this permissions.ini file (located in the Xataface directory) to see what the format should look like. Any settings you place in your application's permissions.ini file will augment or override settings in Xataface's file.
Some core permissions include:
Name
Description
Version
view
Permission to view a record or field. This permission is required to access the view tab, and several other details tabs.
0.6
list
Permission to access the list tab.
0.6
calendar
Permission to access the calendar tab.
0.6
edit
Permission to edit a record or field. This also gives access to the edit tab.
0.6
new
Permission to edit a record or field for the purpose of creating a new record. This permission is required to access the new record form.
0.6
select_rows
Permission to select rows in list view to perform actions on them.
0.6
post
Permission to post a record using HTTP POST
0.6
copy
Permission to copy a record.
0.6
update_set
Permission to perform an update on a result set (i.e. access the update set action).
Permission to delete a record in a relationship. This is stronger than the remove related record permission in that it allows the user to delete the record from the database. See Relationship permissions?
0.6
find
Permission to perform the find action.
0.6
import
Permission to perform the import action (to import records into the database).
0.6
export_csv
Permission to perform the Export CSV action (to export the result set in comma-separated-value format).
0.6
export_xml
Permission to perform the Export XML action (to export the result set as XML).
0.8
translate
Permission to translate a record into another language. This permission provides access to the "translate" tab.
0.8
history
Permission to view history information for a record (e.g. the history tab). This requires that history be enabled.
0.8
edit_history
Permission to edit history information such as undo/redo support for a record.
0.8
navigate
Permission to navigate through records of a table.
0.6
reorder_related_records
Permission to reorder the records of a relationship (this is different than just sorting). It sets a default order for the records. Requires the metafields:order directive to be set for the relationship.
0.6
ajax_save
Permission to save a record through AJAX.
0.8
ajax_load
Permission to load a record through AJAX.
0.8
ajax_form
Permission to access the inline editing ajax form for a record.
0.8
find_list
Permission to search current table.
0.6
find_multi_table
Permission to perform a site-wide search.
0.8
register
Permission to register for an account.
0.8
xml_view
Permission to view a result set as xml.
0.8
view_xml
View the XML for an individual record.
0.8
manage_output_cache
Management permission to clear the output cache.
0.8
manage_migrate
Permission to access the migration tool to migrate between versions.
0.8
manage
Permission to access the management control panel.
0.8
manage_build_index
Permission to rebuild the search index.
0.8
expandable
Whether the record can be expanded in the left nav menu
N/A
Some core roles include:
Name
Permissions Included
Version
READ ONLY
view, list, calendar, view xml, show all, find, navigate, ajax_load, find_list, find_multi_table, rss, export_csv, export_xml, and export_json
0.6
EDIT
All permissions in READ ONLY, and edit, add new related record, add existing related record, add new record, remove related record, reorder_related_records, import, translate, new, ajax_save, ajax_form, history, edit_history, copy, update_set, and select_rows
0.6
DELETE
All permissions in EDIT, and delete and delete found.
0.6
OWNER
All permissions in DELETE except navigate, new, and delete found.
0.6
REVIEWER
All permissions in READ ONLY, and edit and translate.
0.6
USER
All permissions in READ ONLY, and add new related record.
0.6
ADMIN
All permissions in DELETE and xml_view
0.6
MANAGER
All permissions in ADMIN and manage, manage_output_cache, manage_migrate, manage_build_index, and install.
0.6
Extending and Overriding Roles
The cleanest and easiest way to define a new role is to extend an existing role. Xataface allows you to extend roles via the extends keyword. For example, if you wanted to create a role TEST ROLE that contained all of the same permissions as the READ ONLY role, you could define it as follows in your application's permissions.ini file:
[TEST ROLE extends READ ONLY]
If we wanted it to contain the same permissions as READ ONLY but to also allow the edit permission we would define it as:
[TEST ROLE extends READ ONLY]
edit=1
If we wanted to disallow the list permission, we would do something like:
[TEST ROLE extends READ ONLY]
edit=1
list=0
Overriding Existing Roles
You can also redefine existing roles:
[READ ONLY extends READ ONLY]
my_permission=1
This is handy if you have added your own custom permissions that you feel should be included in a core role.
Note that there are some caveats regarding the order of how these roles are defined. Please refer to this forum post for more details: Overriding Roles / Permissions
