feature 2999 : Documentation of menubar function and classes

git-svn-id: http://piwigo.org/svn/trunk@25762 68402e56-0260-453c-a942-63ccdbb3a9ee

2 files changed, 166 insertions, 40 deletions

diff --git a/include/block.class.php b/include/block.class.php
index d0943ebb9..e9a55f4b2 100644
--- a/include/block.class.php
+++ b/include/block.class.php
@@ -19,39 +19,63 @@
 // | USA.                                                                  |
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package functions\menubar
+ */
+
+
+/**
+ * Manages a set of RegisteredBlock and DisplayBlock.
+ */
 class BlockManager
 {
+  /** @var string */
   protected $id;
-  protected $registered_blocks=array();
+  /** @var RegisteredBlock[] */
+  protected $registered_blocks = array();
+  /** @var DisplayBlock[] */
   protected $display_blocks = array();
 
-  public function BlockManager($id)
+  /**
+   * @param string $id
+   */
+  public function __construct($id)
   {
     $this->id = $id;
   }
 
-  /** triggers an action that allows implementors of menu blocks to register the blocks*/
+  /**
+   * Triggers a notice that allows plugins of menu blocks to register the blocks.
+   */
   public function load_registered_blocks()
   {
-    trigger_action('blockmanager_register_blocks', array(&$this) );
+    trigger_action('blockmanager_register_blocks', array(&$this));
   }
-
+  
+  /**
+   * @return string
+   */
   public function get_id()
   {
     return $this->id;
   }
 
+  /**
+   * @return RegisteredBlock[]
+   */
   public function get_registered_blocks()
   {
     return $this->registered_blocks;
   }
 
-  /** registers a block with this menu. usually called as a result of menubar_register_blocks action
-   * @param MenuBlock block
-  */
+  /**
+   * Add a block with the menu. Usually called in 'blockmanager_register_blocks' event.
+   *
+   * @param RegisteredBlock &$block
+   */
   public function register_block(&$block)
   {
-    if ( isset($this->registered_blocks[$block->get_id()] ) )
+    if (isset($this->registered_blocks[$block->get_id()]))
     {
       trigger_error("Block '".$block->get_id()."' is already registered", E_USER_WARNING);
       return false;
@@ -60,23 +84,26 @@ class BlockManager
     return true;
   }
 
-  /** performs one time preparation of registered blocks for display;
-   * triggers the action menubar_prepare_display where implementors can
+  /**
+   * Performs one time preparation of registered blocks for display.
+   * Triggers 'blockmanager_prepare_display' event where plugins can
    * reposition or hide blocks
-  */
+   */
   public function prepare_display()
   {
     global $conf;
     $conf_id = 'blk_'.$this->id;
     $mb_conf = isset($conf[$conf_id]) ? $conf[$conf_id] : array();
-    if ( !is_array($mb_conf) )
+    if (!is_array($mb_conf))
+    {
       $mb_conf = @unserialize($mb_conf);
+    }
 
     $idx = 1;
-    foreach( $this->registered_blocks as $id => $block )
+    foreach ($this->registered_blocks as $id => $block)
     {
-      $pos = isset( $mb_conf[$id] ) ? $mb_conf[$id] : $idx*50;
-      if ( $pos>0 )
+      $pos = isset($mb_conf[$id]) ? $mb_conf[$id] : $idx*50;
+      if ($pos>0)
       {
         $this->display_blocks[$id] = new DisplayBlock($block);
         $this->display_blocks[$id]->set_position($pos);
@@ -84,51 +111,83 @@ class BlockManager
       $idx++;
     }
     $this->sort_blocks();
-    trigger_action( 'blockmanager_prepare_display', array(&$this) );
+    trigger_action('blockmanager_prepare_display', array(&$this));
     $this->sort_blocks();
   }
 
-  /** returns true if the block whose id is hidden
-   * @param string block_id
-  */
+  /**
+   * Returns true if the block is hidden.
+   *
+   * @param string $block_id
+   * @return bool
+   */
   public function is_hidden($block_id)
   {
-    return isset($this->display_blocks[$block_id]) ? false : true;
+    return !isset($this->display_blocks[$block_id]);
   }
 
+  /**
+   * Remove a block from the displayed blocks.
+   *
+   * @param string $block_id
+   */
   public function hide_block($block_id)
   {
-    unset( $this->display_blocks[$block_id] );
+    unset($this->display_blocks[$block_id]);
   }
 
+  /**
+   * Returns a visible block.
+   *
+   * @param string $block_id
+   * @return &DisplayBlock|null
+   */
   public function &get_block($block_id)
   {
     $tmp = null;
-    if ( isset($this->display_blocks[$block_id]) )
+    if (isset($this->display_blocks[$block_id]))
     {
       return $this->display_blocks[$block_id];
     }
     return $tmp;
   }
 
+  /**
+   * Changes the position of a block.
+   *
+   * @param string $block_id
+   * @param int $position
+   */
   public function set_block_position($block_id, $position)
   {
-    if ( isset($this->display_blocks[$block_id]) )
+    if (isset($this->display_blocks[$block_id]))
     {
       $this->display_blocks[$block_id]->set_position($position);
     }
   }
 
+  /**
+   * Sorts the blocks.
+   */
   protected function sort_blocks()
   {
-    uasort( $this->display_blocks, array('BlockManager', 'cmp_by_position') );
+    uasort($this->display_blocks, array('BlockManager', 'cmp_by_position'));
   }
 
+  /**
+   * Callback for blocks sorting.
+   */
   static protected function cmp_by_position($a, $b)
   {
     return $a->get_position() - $b->get_position();
   }
 
+  /**
+   * Parse the menu and assign the result in a template variable.
+   *
+   * @param string $var
+   * @param string $file
+   */
   public function apply($var, $file)
   {
     global $template;
@@ -136,9 +195,9 @@ class BlockManager
     $template->set_filename('menubar', $file);
     trigger_action('blockmanager_apply', array(&$this) );
 
-    foreach( $this->display_blocks as $id=>$block)
+    foreach ($this->display_blocks as $id=>$block)
     {
-      if (empty($block->raw_content) and empty($block->template) )
+      if (empty($block->raw_content) and empty($block->template))
       {
         $this->hide_block($id);
       }
@@ -149,62 +208,126 @@ class BlockManager
   }
 }
 
+
 /**
- * Represents a menu block registered in a Menu object.
+ * Represents a menu block registered in a BlockManager object.
  */
 class RegisteredBlock
 {
+  /** @var string */
   protected $id;
+  /** @var string */
   protected $name;
+  /** @var string */
   protected $owner;
 
-  public function RegisteredBlock($id, $name, $owner)
+  /**
+   * @param string $id
+   * @param string $name
+   * @param string $owner
+   */
+  public function __construct($id, $name, $owner)
   {
     $this->id = $id;
     $this->name = $name;
     $this->owner = $owner;
   }
 
-  public function get_id() { return $this->id; }
-  public function get_name() { return $this->name; }
-  public function get_owner() { return $this->owner; }
+  /**
+   * @return string
+   */
+  public function get_id()
+  {
+    return $this->id;
+  }
+
+  /**
+   * @return string
+   */
+  public function get_name()
+  {
+    return $this->name;
+  }
+
+  /**
+   * @return string
+   */
+  public function get_owner()
+  {
+    return $this->owner;
+  }
 }
 
+
 /**
- * Represents a menu block ready for display in the Menu object.
+ * Represents a menu block ready for display in the BlockManager object.
  */
 class DisplayBlock
 {
+  /** @var RegisteredBlock */
   protected $_registeredBlock;
+  /** @var int */
   protected $_position;
-
+  /** @var string */
   protected $_title;
 
+  /** @var mixed */
   public $data;
+  /** @var string */
   public $template;
+  /** @var string */
   public $raw_content;
 
-  public function DisplayBlock($registeredBlock)
+  /**
+   * @param RegisteredBlock &$block
+   */
+  public function __construct($block)
   {
-    $this->_registeredBlock = &$registeredBlock;
+    $this->_registeredBlock = &$block;
   }
 
-  public function &get_block() { return $this->_registeredBlock; }
+  /**
+   * @return &RegisteredBlock
+   */
+  public function &get_block()
+  {
+    return $this->_registeredBlock;
+  }
 
-  public function get_position() { return $this->_position; }
+  /**
+   * @return int
+   */
+  public function get_position()
+  {
+    return $this->_position;
+  }
+
+  /**
+   * @param int $position
+   */
   public function set_position($position)
   {
     $this->_position = $position;
   }
 
+  /**
+   * @return string
+   */
   public function get_title()
   {
     if (isset($this->_title))
+    {
       return $this->_title;
+    }
     else
+    {
       return $this->_registeredBlock->get_name();
+    }
   }
 
+  /**
+   * @param string
+   */
   public function set_title($title)
   {
     $this->_title = $title;
diff --git a/include/menubar.inc.php b/include/menubar.inc.php
index b624111ca..9c2987349 100644
--- a/include/menubar.inc.php
+++ b/include/menubar.inc.php
@@ -22,14 +22,16 @@
 // +-----------------------------------------------------------------------+
 
 /**
- * This file is included by the main page to show the menu bar
- *
+ * @package functions\menubar
  */
 
 include_once(PHPWG_ROOT_PATH.'include/block.class.php');
 
 initialize_menu();
 
+/**
+ * Setups each block the main menubar.
+ */ 
 function initialize_menu()
 {
   global $page, $conf, $user, $template, $filter;
@@ -329,4 +331,5 @@ function initialize_menu()
   }
   $menu->apply('MENUBAR',  'menubar.tpl' );
 }
+
 ?>
\ No newline at end of file