How to implement actions in your code
From Joomla! Documentation
Revision as of 09:09, 17 March 2011 by Quodo
This article or section is incomplete, which means it may be lacking information. You are welcome to assist in its completion by editing it as well. If this article or section
This article or section is in the process of an expansion or major restructuring. You are welcome to assist in its construction by editing it as well. If this article or section
This document is intended to be a summary for developers who implement action/permissions into their component.
You are familiar with setting up permissions as a backend user with Configure permission in Joomla 1.6. Your component is set up with
- an Options toolbar button to set permissions for the component
- permission setting panes similar to the Category Permissions panes in the Category Manager.
Inheritance works with an asset for each level and there are four levels in the Joomla core:
- Global Configuration
- Component Options: the component inherits permissions from the global configuration.
- Category: A category inherits permissions either from its parent category, or if it is the root category from the component.
- Article: An article inherits permissions from the category it is in.
A 3rd party developer can create even more or other levels if a component would ‘need’ it. E.g. a gallery component might have galleries as the objects within a component. These galleries then have the Component Options as parent and images as child-objects.
Joomla has a number of actions, which due to their nature are not defined on each level:
- core.login.site – only Global Configuration
- core.login.admin – only Global Configuration
- core.admin – Global Configuration and Component Manager
- core.manage – Global Configuration and Component Manager
- core.create – Global Configuration, Component Manager, Category level
- core.delete – all levels: Global Configuration, Component Manager, Category level, Article level
- core.edit – all levels: Global Configuration, Component Manager, Category level, Article level
- core.edit.state – all levels: Global Configuration, Component Manager, Category level, Article level
- core.edit.own – Global Configuration, Component Manager, Category level
A 3rd party developer can create component specific actions, and that at any level (due to Not set meaning implicitly denied). The naming convention is component.action, without the com_ in component (e.g. mycomponent.vote for the vote action in com_mycomponent). These actions can be defined in the component's access.xml.
Permissions for actions can have values “Null”, ‘0’ and ‘1’
- Null is equivalent of Not Set or Inherited and as such implicitly Denied (“Not Allowed” in Debug Permissions Report).
- 0 is equivalent to Explicitly Denied (“Forbidden” in Debug Permissions Report).
- 1 is equivalent to Allowed (“Allowed” in Debug Permissions Report).
Inheritance makes that if an action is explicitly denied in a higher level it always is denied for all the children no matter what their setting is. Also, if an action is allowed, it is allowed for all the children unless it is explicitly denied for one of them (and therefore for its children as well). And finaly, if an action is not set nor inherited (and the parents are not explicitly denied nor allowed) then it is implicitly denied.
You can check if the logged in user has permission for an action for a specific asset:
for action core.admin and asset com_mycomponent (API16:JUser/authorise).
Example of inheritance
Within the Category Manager for Articles, three categories are set up: Animals, Pets and Dogs. Dogs is a child of Pets and Pets is a child of Animals. There is an article "About my favourite dog" in the Pets category. These can be their assets, where asset id is the id of the asset in the #__assets table.
- Global Configuration
- The Root Asset with asset id 1 and parent asset 0.
- Component Options->Permissions
- Article Manager: the com_content asset with id 8 and parent asset 1 (the Root Asset).
- Animals category (category id 1): asset com_content.category.1 with asset id 20 and parent asset 8.
- Pets category (category id 2): asset com_content.category.2 with asset id 30 and parent asset 20.
- Dogs category (category id 3): asset com_content.category.2 with asset id 40 and parent asset 30.
- Article "About my favourite dog" (id 42 in #__content): with asset com_content.article.42 and asset id 100 and parent asset 40.
The article inherits permissions from the Dogs category, which inherits permissions from the Pets category, which inherits permissions from the com_content component which in turn inherits permissions from the Root Asset. This is where the parent ids of the assets are used.
Getting an overview of all permissions
The Debug Permissions Report shows all (core) permissions for each asset. It can be found here: First set Debug System to Yes (Backend > Site > Global Configuration > System > Debug Settings), then go to Backend > Users > User Manager. Every user and user group has a Debug Permissions Report button.
It shows the inheritance since all Asset Names are set up in a tree and it shows if actions are Not Allowed (implicitly denied), Allowed or Forbidden (explicitly denied).
Joomla! 1.6 stores all categories for all components in #__categories. The extension field shows in which component a category is used. You can get a list of categories for which a specific action is allowed with
where $component is the component whose categories you want (e.g. com_content) and $action is the specific action (e.g. core.create) is allowed.
If I allow core.edit on a category (e.g. Pets) then it is allowed for this category and its subcategories (e.g. Dogs) and its articles (e.g. the one about my favourite dog) as well. This usergroup may edit the Pets category as well as its children (core.edit for com_content.category.2 when Pets is category 2; and subcategories/articles are all on inherit).
So core.edit says something about the asset it belongs to and its children; if a category has core.edit permission then that category and its children can be edited.
If the a category (e.g. Pets, asset: com_content.category.2) allows core.create for the usergroup a user can create categories and articles as children within the Pets category. E.g. besides the dogs subcategory they can make a cats subcategory and/or create an article about their favourite pet within this Pets category and its children.
So core.create says something about the children of the asset it belongs to (the children of com_content.category.2); if a category has core.create permission then the user is allowed to create categories/articles within this category.
Note: this part needs information about the core.delete action (http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=25357).
What I expected was that core.delete would say something about the children of the asset it belongs (like core.create) rather than the asset itself (like core.edit). It does seem to work like in A: I can delete an article from the trash (empty trash button available not trash button) when its parent item allows core.delete for the usergroup, but I cannot delete an article from the trash (trash button available not empty trash button) when its parent does not have the core.delete allowed for the usergroup (implicit denial due to inheritance, no parent explicitly denied it). But then why is there a core.delete permission for articles as articles never have children? And why does the description on core.delete for categories mention “New setting for delete action on this category…” whereas the core.create mentions “New setting for create actions in this category…” (difference in “on” and “in”)? This one I don't seem to understand.