utilisation.gtw

~~LANG:EN@enman:rights2/use~~

Quand vous voulez que votre module fonctionne selon des droits, il vous faut
durant la réalisation de ce module :

   * déterminer des sujets (droits) que vous utiliserez
   * éventuellement les enregistrer dans le système de droits utilisé par le
     driver que vous indiquez à jAcl2 : dans un annuaire LDAP si vous utilisez
     un driver LDAP (non fourni) ou une base de données si vous
     utilisez [[configuration|par exemple le driver jAcl2.db]].

Ensuite vous pouvez utiliser les méthodes statiques de jAcl2 pour savoir si
l'utilisateur courant a tel droit sur tel ou tel sujet. 

Si le driver gère des groupes d'utilisateurs, vous n'avez pas à les indiquer
lors de ces interrogations : le driver s'en occupe automatiquement. Notez qu'un
driver pour jAcl2 peut utiliser jAuth pour l'authentification.

===== Configuration =====

Avant toute chose vous devez installer le module jacl2 :

<code php>
php cmd.php installmodule jacl2
</code>


Ensuite vous devez indiquer quel driver vous utilisez pour jAcl2.

Les drivers sont des plugins stockés dans un répertoire @@F@acl2@@ d'un dépôt de
plugins. Un plugin pour jAcl2 est une classe @@C@fooAcl2Driver@@ (foo étant le nom du
plugin) qui doit implémenter l'interface @@I@jIAcl2Driver@@ et qui est enregistrée
dans un fichier @@F@foo.acl2.php@@. Par exemple le driver "db" est stocké dans
@@F@db/db.acl2.php@@ et est défini dans la classe @@C@dbAcl2Driver@@.

Pour indiquer le driver, vous avez deux choix :

   * Si il est fourni par un module, comme jacl2db, installez le module. Pour jacl2db
     voyez [[configuration|la configuration de jacl2db]].
   * Si vous avez juste un plugin fourni, stockez le dans un dépôt de plugin et
     indiquez sont nom dans une section @@[acl2]@@ de la configuration générale :

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

Au niveau de l'option @@driver@@, vous devez y mettre le nom du driver utilisé.

===== Interrogation du système de droit =====

Comme jAcl2 se charge de découvrir l'utilisateur actuel, vous n'avez qu'une
méthode statique de jAcl2 à connaître pour 99% des cas : @@M@jAcl2::check()@@.

==== jAcl2::check ====

C'est probablement la méthode que vous utiliserez le plus avec jAcl2. Elle
permet de savoir si l'utilisateur a tel ou tel droit, et renvoie donc true ou
false. C'est une méthode statique. Exemple :

<code php>
if( jAcl2::check("cms.articles.create")){
   // code à exécuter si l'utilisateur a le droit de créer un article

}else{
   // code à exécuter si l'utilisateur n'a pas le droit de créer un article
}
</code>

Pour interroger sur une ressource précise :

<code php>
$article_id = "opinions";

if( jAcl2::check("cms.articles.update", $article_id)){
   // code à exécuter si l'utilisateur a le droit de modifier l'article indiqué

}else{
   // code à exécuter si l'utilisateur n'a pas le droit de modifier l'article indiqué
}
</code>

Une valeur vide ou "-" pour l'identifiant de la ressource indique "pour toute ressource".
Avant Jelix 1.4.1, seule la valeur vide spécifié cet état.

==== Vérification automatique ====

L'installateur du module jacl2 installe le plugin jacl2 pour le coordinateur.
Il vérifie automatiquement les droits d'une action avant l'exécution d'un
contrôleur.

Vous devriez donc avoir ceci dans la configuration :

<code ini>
[coordplugins]
jacl2 = 1
</code>

La configuration du plugin se trouve dans une section @@coordplugin_jacl2@@ de la configuration
principale (Avant Jelix 1.5, c'était dans un fichier séparé).
 

<code ini>
[coordplugin_jacl2]
on_error=2
error_message="jacl2~errors.action.right.needed"
on_error_action="jelix~error:badright"
</code>

   * @@on_error@@ doit être égal à 1 pour les points d'entrée des service web (soap, jsonrpc, xmlrpc...).
   * @@error_message@@ indique le selecteur de la chaine localidée contenant un message d'erreur, affiché quand les droits ne sont pas bons
   * @@on_error_action@@ indique le selecteur de l'action où l'application doit redirigé si la vérification échoue.

Le plugin essaiera de récupérer les paramètres de plugins suivant dans les contrôleurs :
@@jacl2.right@@, @@jacl2.rights.and@@, @@jacl2.rights.or@@. Ces paramètres doivent contenir
des noms de sujets de droits. Le plugin testera donc si l'utilisateur a les droits indiqués.

Pour vérifier un seul droit, utilisez @@jacl2.right@@ :
<code php>

   public $pluginParams = array(
        '*' => array( 'jacl2.right'=>'sujet', ...)
        ...
   );
</code>

Pour vérifier une série de droits que l'utilisateur doit posséder, utilisez @@jacl2.rights.and@@ :

<code php>

   public $pluginParams = array(
     '*' => array( 'jacl2.rights.and'=>array('sujet1', 'sujet2', ..)
            ),
        ...
   );
</code>

Ou encore, pour vérifier que l'utilisateur possède un des droits parmi une liste, utilisez @@jacl2.rights.or@@ :

<code php>

   public $pluginParams = array(
     '*' => array( 'jacl2.rights.or'=>array('sujet1', 'sujet2', ..)
            ),
        ...
   );
</code>

==== Plugins de template ifacl2 et ifnotacl2 ====

Des plugins de templates sont disponibles pour générer des portions de contenus
en fonction des droits. Leurs arguments sont exactement les mêmes que
@@jAcl2::check()@@.

<code>
  {ifacl2 "cms.articles.create"}
    <input type="button" value="Créer un article" />
  {else}
   <p>Vous ne pouvez pas créer d'articles.</p>
  {/ifacl2}
</code>

Il y aussi @@{ifnotacl2}@@, le contraire de @@{ifacl2}@@, c'est à dire qui
teste si l'utilisateur n'a **pas** le droit indiqué.

La même chose avec une ressource :

<code>
  {ifacl2 "cms.articles.update", $article_id}
    <input type="button" value="Modifier l'article" />
  {/ifacl2}
</code>