add block support and comments

README.md

@@ -1,34 +1,30 @@
-## AclUtilities ##
+# AclUtilities Plugin for CakePHP #
 
-AclUtilities is a Cakephp plugin.
+AclUtilities permits to translarently display or hide links in view according to Acl rules.
 
-It permits to only display the link for which the user has access.
+## Installation ##
 
-For now, AclUtilities contains just one Helper but it has been made into a plugin to make it's use simpler.
-
-Installation:
-
-1. in the views, replace $this->Html->link() by $this->Acl->link()
+* in the views, replace $this->Html->link() by $this->Acl->link()
 
 example:
 
 <?php echo $this->Html->link(__('List Posts', true), array('action' => 'index')); ?>
 
 <?php echo $this->Html->link(__('Edit User', true), array('controller'=>'User','action' => 'edit')); ?>
 
-replaced by
+replaced by:
 
 <?php echo $this->Acl->link(__('List Posts', true), array('action' => 'index')); ?>
 
 <?php echo $this->Acl->link(__('Edit User', true), array('controller'=>'User','action' => 'edit')); ?>
 
 Be sure to use an array format for the URL.
 
-2. in the AppController, add the helper AclUtilities.Acl
+* in the AppController, add the helper AclUtilities.Acl
 
 var $helpers = array([...], 'AclUtilities.Acl');
 
-3. If you are using Auth->allowedActions or Auth->allow()
+* If you are using Auth->allowedActions or Auth->allow()
    Then you have to move them all into AppController::beforeFilter() like the following:
 
   function beforeFilter() {
@@ -49,12 +45,10 @@ var $helpers = array([...], 'AclUtilities.Acl');
 
 And this is it; your links are now only displayed when they can be accessed!
 
+## More Examples ##
 
 
-** More examples **
-
-
-1. use of the option 'wrapper': 
+* use of the option wrapper: 
 
 <ul>
   <li>
@@ -68,7 +62,7 @@ And this is it; your links are now only displayed when they can be accessed!
                               ,array('wrapper'=>'li'); ?>
 <ul>
 
-2. another use of the wrapper
+* another use of the wrapper
 
 <div class="myClass">
   <?php echo $this->Html->link(__('List Posts', true), array('action' => 'index')); ?>
@@ -78,7 +72,7 @@ And this is it; your links are now only displayed when they can be accessed!
                            ,array('action' => 'index')
                            ,array('wrapper'=>'<div class="myClass">%s</div>'); ?>
 
-3. use of $this->Acl->check()
+* use of $this->Acl->check()
 
 <?php if ($this->Acl->check(array('action' => 'index'))): ?>
   <div class="myClass">

acl_utilities_app_controller.php

@@ -1,7 +1,11 @@
 <?php
+/**
+ * AclUtilities base controller
+ *
+ * @package AclUtilities
+ */
 class AclUtilitiesAppController extends AppController
 {
   public $plugin = 'AclUtilities';
   public $helpers = array('Acl');
-  //...
 }

acl_utilities_app_model.php

@@ -1,6 +1,10 @@
 <?php
+/**
+ * AclUtilities base model
+ *
+ * @package AclUtilities
+ */
 class AclUtilitiesAppModel extends AppModel
 {
   public $plugin = 'AclUtilities';
-  //...
 }

views/helpers/acl.php

@@ -1,12 +1,19 @@
 <?php
+/**
+ * Acl Helper
+ *
+ * Acl view helper allowing to check the Acl from the views
+ *
+ * @package AclUtilities
+ * @subpackage AclUtilities.views.helpers
+ */
 class AclHelper extends AppHelper
 {
-  public $name = 'Acl';
   public $helpers = array('Session', 'Html');
 
   /**
    *
-   * foreign key of the aro
+   * foreign key of the aro Usually the User.id
    * @var integer
    */
   private $__foreignKey;
@@ -21,27 +28,45 @@ class AclHelper extends AppHelper
   /**
    *
    * Acl Component used for checking the access
-   * @var AclComponent²
+   * @var AclComponent
    */
   private $__acl;
 
+  /**
+   * List of current blocks
+   * @var array
+   */
+  private $__blocks;
+
+  /**
+   *
+   * Inits some variables
+   */
   public function beforeRender()
   {
     parent::beforeRender();
 
+    $this->__blocks = array();
+
     $this->__allowedActions = Configure::read('AclUtilities.allowedActions');
 
     $this->__foreignKey = $this->Session->read('Auth.User.id');
 
     // if not logged in, then no need for the Acl
-    if (is_null($this->__foreignKey))
+    if (!$this->isLoggedin())
       return;
 
     App::import('Component', 'Acl');
     $this->__acl = new AclComponent();
-  }
 
 
+  }
+
+  /**
+   *
+   * Check if the url in param can be accessed by the current user
+   * @param array $url
+   */
   public function check($url)
   {
     $params = $this->params;
@@ -58,7 +83,7 @@ public function check($url)
       return true;
 
     // if not logged in, then no need for the Acl
-    if (is_null($this->__foreignKey))
+    if (!$this->isLoggedin())
       return false;
 
     // find the aco node
@@ -78,11 +103,26 @@ public function check($url)
     return $this->__acl->check($aro, $aco);
   }
 
+  /**
+   *
+   * call Html->link() with same params if the user has access to the link
+   * can contains 'wrapper in $option which will wrap the link if displayed
+   * @param string $title
+   * @param array $url
+   * @param array $options
+   * @param string $confirmMessage
+   */
   public function link($title, $url = null, $options = array(), $confirmMessage = false)
   {
     if (!$this->check($url))
       return '';
 
+    // set all the block to true so they will get displayed
+    foreach ($this->__blocks as $id =>$val)
+    {
+      $this->__blocks[$id] = true;
+    }
+
     if (isset($options['wrapper']))
     {
       if (isset($this->Html->tags[$options['wrapper']]))
@@ -105,8 +145,42 @@ public function link($title, $url = null, $options = array(), $confirmMessage =
 	return sprintf($wrapper, '', $link);
   }
 
+  /**
+   *
+   * return true if the user if logged in or false otherwise
+   */
   public function isLoggedin()
   {
     return !is_null($this->__foreignKey);
   }
+
+  /**
+   *
+   * You must use  Acl->endBlock() before the end of the view
+   * Begin a block which will be displayed only
+   * if there is an Acl->link() successful
+   * before the endBlock
+   */
+  public function startBlock()
+  {
+    $this->__blocks[] = false;
+    ob_start();
+  }
+
+  /**
+   *
+   * End the current block.
+   * This block is displayed if it contains
+   * at least one successfully displayed link
+   */
+  public function endBlock()
+  {
+    $lastid = count($this->__blocks) - 1;
+    if ($this->__blocks[$lastid])
+      ob_end_flush();
+    else
+      ob_end_clean();
+
+    unset($this->__blocks[$lastid]);
+  }
 }