From 0a76030ead6201fe71593d7e9f47512256b065df Mon Sep 17 00:00:00 2001 From: mistic100 Date: Sun, 1 Dec 2013 15:03:38 +0000 Subject: feature 2999 : Documentation of menubar function and classes git-svn-id: http://piwigo.org/svn/trunk@25762 68402e56-0260-453c-a942-63ccdbb3a9ee --- include/block.class.php | 199 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 161 insertions(+), 38 deletions(-) (limited to 'include/block.class.php') 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; -- cgit v1.2.3