How to add basic ACL support to your extension

UPDATE April 3, 2012: Since ACL Manager 1.2.0 it is possible to set the permissions for extensions that do not support Joomla ACL by default via ACL Manager. Find out more in the blog post "Upcoming: ACL support for any component".

Last week I wrote the article "Is your extension really Joomla 1.7 ready?". In that article I tested 10 Joomla 1.7 extension for ACL support. The results were disappointing, several extensions did not even support the most basic Joomla ACL permissions: Configure and Access Component, so Joomla end users can not define which User Groups are able to access a specific component.

Basic Joomla ACL support in extensions

As promised I would write an article for developers about how to implement the basic ACL support in your own extension. My definition of basic ACL support is that an extension contains two permissions at least:

1. Configure: To configure the access settings via the 'Options' toolbar button
2. Access Component: To define which group is able to access/manage the component

Supporting permissions above is the minimum, you can add additional permissions like create, edit, delete, etc... or even add your custom permissions only valid for your extension. I will cover this in an other article, but for now just the minimum ACL support.

Basic Joomla ACL support with just 18 lines of code

Yes, it is true. You can support Joomla ACL by adding just 18 lines of code to your extension! So if your "Joomla 1.7" extension does not support Joomla ACL yet, take a few minutes and implement the code below in just 4 steps to support the Joomla ACL and deserve the Joomla 1.7 compatible label.

Note: com_foobar is an example component name in the code below, replace this with own your component name.

Step 1: Add/modify config.xml

The first step is to define the possible actions for your extensions. We want to add support for Configure: (core.admin) and Access Component (core.manage). We need to define these actions in the config.xml file of your extension. Create the following file and add the code below.

File: administrator/components/com_foobar/config.xml

<?xml version="1.0" encoding="utf-8"?>
<config>	
	<fieldset name="permissions" label="JCONFIG_PERMISSIONS_LABEL" description="JCONFIG_PERMISSIONS_DESC">
		<field name="rules" type="rules" label="JCONFIG_PERMISSIONS_LABEL" filter="rules" component="com_foobar" section="component">
			<action name="core.admin" title="JACTION_ADMIN" description="JACTION_ADMIN_COMPONENT_DESC" />
			<action name="core.manage" title="JACTION_MANAGE" description="JACTION_MANAGE_COMPONENT_DESC" />
		</field>
	</fieldset>
</config>

If you already have the config.xml file you just need to add the permissions fieldset part. As you can see in the code above we have added two actions, core.admin and core.manage. The 'core' part of the action names means that this action is a Joomla core actions. If you add custom actions you need to use the format foobar.actionname, more about this in a next article. Don't forget to replace the component name (com_foobar) with the component name of your extension.

Step 2: Add access check

The next step is to add the access check to the entire component, add the following code just below the direct access check (defined('_JEXEC') or die;).

File: administrator/components/com_foobar/foobar.php

// Access check.
if (!JFactory::getUser()->authorise('core.manage', 'com_foobar')) {
	return JError::raiseWarning(404, JText::_('JERROR_ALERTNOAUTHOR'));
}

So a user without Access Component permission is not able to access the component and will get an 404 error message. The component will not be visible in the components menu if the user is not allowed to access the component. So the user will only see the error message via a direct link to the component. Otherwise the user possible will not even know the extension is there.

Step 3: Add the 'Options' toolbar button

Ok, almost there. We only need to add the Options toolbar button in the extension toolbar. You will probably already have the addToolbar() function in your view file of the extension, extend this by adding the following code.

File: administrator/components/com_foobar/views/foobars/view.html.php

// Options button.
if (JFactory::getUser()->authorise('core.admin', 'com_foobar')) {
	JToolBarHelper::preferences('com_foobar');
}

This code adds the Options button to the toolbar and also do an access check so only User Groups with Configure permission for the extension are able to see and click the button to configure the extension. You may need to repeat this for more views if applicable.

Step 4: Add one language string

Users are now able to click on the Options button in the toolbar. By clicking on this button a modal window will show up where you can set the permissions of the extension. The title of this window needs to be added to your language file, so add the following language string to your language file(s).

File: administrator/language/en-GB/en-GB.com_foobar.ini

COM_FOOBAR_CONFIGURATION="FooBar Options"

That's all!

Done! This is all what is needed to add basic Joomla ACL support to your own extension as a Joomla developer. 18 lines of codes, including 2 comment lines and one language string. Not too difficult I think, agree?

So please add this to all your components so we make our Joomla end users happy by offering the possibility to define the Configure and Access Component permission for each installed Joomla extension.

Hopefully more extensions are supporting Joomla ACL in my next test of 10 Joomla extensions!