View source for Table Advanced API Guide

== ACL Assets ==

Joomla provides the ACL (Access Control List) framework for defining permissions which specify whether or not each user group may create, update or delete items; see for example  [[J3.x:Access_Control_List_Tutorial]], [[J3.x:Developing_an_MVC_Component/Adding_ACL]]. These permissions may be set within the admin backend within the permissions tabs of the edit forms, and can be at several levels:

* at an overall component level (specified on the Global Configuration page)
* for individual categories of a component (specified when you edit a category of that component)
* for individual items of a component (eg article, contact), specified when editing that component item

Joomla stores all these permissions as "rules" within the <tt>assets</tt> table, and the <tt>name</tt> field defines which of the above 3 cases the asset record refers to. For example, for com_content possible values of the <tt>name</tt> field are as follows:

* "com_content" – the ACL rules related to performing actions upon articles in general
* "com_content.category.2" – the ACL rules related to articles having a category which has id=2
* "com_content.article.4" – the ACL rules related to the article with id=4.

If a component allows setting ACL permissions at the individual record level, then the record should have a column called <tt>asset_id</tt>, and the value in this field of a record will be the id of the associated record in the <tt>assets</tt> table (ie the <tt>asset_id</tt> field is a foreign key, pointing to the asset record in the <tt>assets</tt> table).

The Table class has 2 public functions and 3 protected functions associated with managing assets.

<tt>getRules()</tt>

You might expect that after you had called <tt>load()</tt> to load a record you could use this function to find the associated asset rules. However it doesn't (it just returns null unless a previous <tt>setRules()</tt> call has been made) and to find the existing rules you need to read the associated <tt>assets</tt> record yourself. So it's arguably of little value outside core Joomla development. 

<tt>setRules(mixed $input)</tt>

This function enables you to define the ACL rules which should be applied against this record. In array form a set of rules would be like the example below:

<tt>array("core.edit" => array(10 => 1, 11 => 0), "core.delete" => array(10 => 0, 11 => 1))</tt>

where 10 and 11 are ids of usergroups, and 1 is Allowed and 0 is Denied. In this example:
* core.edit entry: usergroup 10 is allowed to edit the item, while usergroup 11 is denied edit access
* core.delete entry: usergroup 11 can delete the item, while usergroup 10 is denied delete access

The <tt>$input</tt> parameter can be rules in the above array format, or in the equivalent json-encoded format, or in the Joomla Rules object format which is generated from passing either form to the Rules class constructor.

If you call <tt>setRules()</tt> to set the ACL permissions which should be applied to the record, and then call <tt>store()</tt> to save the record to the database, then the Table class functionality will update also the associated record in the <tt>assets</tt> table; you don't have to do this yourself.

However, in writing new assets records the Table class needs to know an additional 3 items of information, as you can see by browsing the <tt>assets</tt> records using phpmyadmin, for example. These 3 items of information it requests by calling 3 protected functions, which Joomla expects that you will provide in your own table class which inherits from Joomla Table. These are

* <tt>_getAssetName()</tt> – to provide the <tt>name</tt> field – this is usually of the form "com_example.item.12"
* <tt>_getAssetTitle()</tt> - to provide the <tt>title</tt> field – this is usually the title of the com_example item
* <tt>_getAssetParentId()</tt> – to provide the position of the asset record in the asset hierarchy (implemented as a tree structure in the <tt>assets</tt> table using the Nested Model), by returning the parent asset id. For a <tt>com_example</tt> item this would usually be the record with just "com_example" as the name, ie the general ACL permissions for the <tt>com_example</tt> component. 

Examples of these are in the sample module code at the end of this guide, and in [[J3.x:Developing_an_MVC_Component/Adding_ACL]].

As an aside, note that Joomla itself doesn't use the above functionality for handling editing of the permissions within the admin backend. Instead it uses the following approach: 

* The permissions section of the admin edit form is output from a Rules form field type, one of the Joomla [[Standard form field types]].
* The PHP code of the Rules form field type prefills the existing permissions (in the edit form) by reading the asset data from the <tt>assets</tt> table (using the value inserted into the hidden <tt>asset_id</tt> field in the form to find the first asset record, and then traversing up the tree)
* When a permission is changed in an HTML select element in the form, then an ajax call is made to the server to update the asset record. The values for the other fields (name, title, parent id) are inferred from the URL parameters
* When Save etc is pressed to submit the form, then all the HTML select elements in the permissions tab are set to disabled, so that their values are not passed to the server in the HTTP POST. (This is done in the "submitbutton" javascript inserted within the component edit.php layout file.) 

If you use the above paradigm, then you can avoid the necessity of using the <tt>setRules()</tt> functionality and having to provide methods for the above 3 protected functions.