Skip to content

Commit

Permalink
feature 2999 : Documentation of menubar function and classes
Browse files Browse the repository at this point in the history 
git-svn-id: http://piwigo.org/svn/trunk@25762 68402e56-0260-453c-a942-63ccdbb3a9ee
  • Loading branch information
@mistic100
mistic100 committed Dec 1, 2013
1 parent e8b111d commit 0a76030
Show file tree
Hide file tree
Showing 2 changed files with 166 additions and 40 deletions.
199 changes: 161 additions & 38 deletions include/block.class.php
View file
Expand Up @@ -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;
Expand All @@ -60,85 +84,120 @@ public function register_block(&$block)
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);
}
$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;

$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);
}
Expand All @@ -149,62 +208,126 @@ public function apply($var, $file)
}
}


/**
* 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;
Expand Down
7 changes: 5 additions & 2 deletions include/menubar.inc.php
View file
Expand Up @@ -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;
Expand Down Expand Up @@ -329,4 +331,5 @@ function initialize_menu()
}
$menu->apply('MENUBAR', 'menubar.tpl' );
}

?>

0 comments on commit 0a76030

Please sign in to comment.