use.gtw

When you want your module operates on rights, you need during the implementation of this module:

   - Identify the subjects and values that you want to use or create
   - Possibly record this subject and values in the system of rights used by the driver that you enable in jAcl: in LDAP if you use a driver ldap (not supplied for the moment) or a database if you use such as driver jAcl.db.

Then you can use the static methods of jAcl to know if the current user has right on a subject.

If the driver manages user groups, you do not have to specify them when you call jAcl: the driver takes care of automatically. Note that a driver can use jAuth for authentication.

===== Configuration =====

	
First of all you must specify which driver you use for jAcl. The drivers are plugins stored in a directory //acl// of a repository of plugins. A plugin for jAcl is a class fooAclDriver (foo is the name of the plugin) which must implement the interface jIAclDriver and is stored in a file foo.acl.php. For example, the driver "db" is stored in //db/db.acl.php// and defines the class dbAclDriver.

In the configuration of the application, you should have a section //acl//:

<code ini>
[acl]
driver=db
</code>

The //driver// option indicates the name of the driver.

===== Using jAcl =====

You have only two static methods to know: //check// and //getRight//.

==== jAcl::getRight ====

jAcl::getRight() allows you to know all values attached to the given subject, and for the current user. So it gives you all rights of the user for the given subject.

<code php>
  $list = jAcl::getRight("cms.articles");
</code>

If we follow the example of the section about jAcl.db, if the user is a "reader", so the list will be:

<code php>
  array('LIST','READ');
</code>

If he is a writer:

<code php>
  array('LIST','READ', 'CREATE','UPDATE','DELETE');
</code>

You can indicates a resource, for example "opinions":

<code php>
  $list = jAcl::getRight("cms.articles", "opinions");
</code>

If the user is a "reader", the list will be:
<code php>
  array('LIST','READ', 'UPDATE');
</code>

If he is a" writer", the list is the same as previous, because all writers can modify any articles, as defined in the example of jAcl.db.
<code php>
  array('LIST','READ', 'CREATE','UPDATE','DELETE');
</code>


==== jAcl::check ====

This is probably the method you use most with jAcl. It helps to know if the user has a particular right, and therefore return true or false. Example:

<code php>
if( jAcl::check("cms.articles","CREATE")){
   // here the code to execute when the user has the right to create an article

}else{
   // here the code to execute when the user is not allowed to create an article
}
</code>

Of course, we can specify a resoure:

<code php>
$article_id = "opinions";

if( jAcl::check("cms.articles","UPDATE", $article_id)){
   // here the code to execute when the user has the right to modify the given article
}else{
   // here the code to execute when the user is not allowed to modify this article
}
</code>

==== Automatic check ====
	
In controllers where you want to check the rights automatically, you can use the plugin jacl for the coordinator.

To do so, enable the plugin jacl in the application configuration:

<code ini>
[plugins]
jacl = jacl.coord.ini.php
</code>

Copy the file lib/jelix/plugins/coord/jacl/jacl.coord.ini.php.dist to var/config/index/jacl.coord.ini.php

Edit this file to indicate which actions to go in case of bad rights, or the message to display.

And in your controller, put the following values in the property $pluginParams:

<code php>

   public $pluginParams = array(
         '*'=>array('jacl.right'=>array('subject', 'value') ...)
        ...
   );
</code>

Or also, to verify several rights:

<code php>

   public $pluginParams = array(
     '*'=>array('jacl.rights.and'=>array(
         array('subject', 'value'),
         array('subject', 'value'),
         )...
      ),
        ...
   );
</code>

or to verify if the user has at least on right in a list of rights:

<code php>

   public $pluginParams = array(
     'jacl.rights.or'=>array(
         array('subject', 'value'),
         array('subject', 'value'),
         ...
      ),
        ...
   );
</code>

==== Template plugins ifacl and ifnotacl ====

Some plugins for jTpl are available to check rights inside a template, so to display or not some parts of a template. Arguments are same as jAcl::check().

<code>
  {ifacl "cms.articles","CREATE"}
    <input type="button" value="Create an article" />
  {else}
   <p>You cannot create articles.</p>
  {/ifnotacl}
</code>

ifnotacl is of course the opposite of ifacl.

Same thing with a resource:
<code>
  {ifacl "cms.articles","UPDATE", $article_id}
    <input type="button" value="Modify the article" />
  {/ifacl}
</code>