Skip to content

permissions.ini file

Jump to bottom Edit New page
Steve Hannah edited this page Sep 2, 2016 · 1 revision

Table of Contents

The permissions.ini File

toc

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:

  1. Permissions
  2. 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.

Our actions.ini file entry might look something like:

[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:

[EDITOR] view=1 edit=1 [MANAGER] view=1 edit=1 delete=1

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). 0.8
add new related record Permission to add a new record to a relationship. See Relationship Permissions 0.6
add existing related record Permission to add an existing record to a relationship. See Relationship Permissions 0.6
view related records Permission to view the records in a relationship. See Relationship Permissions 1.0
delete Permission to delete a record. 0.6
delete found Permission to access the delete found set action (to delete multiple records at a time). 0.6
show all Permission to access show all records action. 0.6
remove related record Permission to remove a record from a relationship. See Relationship Permissions 0.6
delete related record 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

See Also

Add a custom footer
Add a custom sidebar
Clone this wiki locally