aboutsummaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authormistic100 <mistic@piwigo.org>2013-12-01 15:03:38 +0000
committermistic100 <mistic@piwigo.org>2013-12-01 15:03:38 +0000
commit0a76030ead6201fe71593d7e9f47512256b065df (patch)
tree6b2eb09fa3da0ef7d628213c35a9fa835caa9d3d /include
parente8b111d1af67728b52efa5b48d3a22800d973ffc (diff)
feature 2999 : Documentation of menubar function and classes
git-svn-id: http://piwigo.org/svn/trunk@25762 68402e56-0260-453c-a942-63ccdbb3a9ee
Diffstat (limited to 'include')
-rw-r--r--include/block.class.php199
-rw-r--r--include/menubar.inc.php7
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