Changeset 25762


Ignore:
Timestamp:
12/01/13 16:03:38 (6 years ago)
Author:
mistic100
Message:

feature 2999 : Documentation of menubar function and classes

Location:
trunk/include
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/include/block.class.php

    r19703 r25762  
    2020// +-----------------------------------------------------------------------+ 
    2121 
     22/** 
     23 * @package functions\menubar 
     24 */ 
     25 
     26 
     27/** 
     28 * Manages a set of RegisteredBlock and DisplayBlock. 
     29 */ 
    2230class BlockManager 
    2331{ 
     32  /** @var string */ 
    2433  protected $id; 
    25   protected $registered_blocks=array(); 
     34  /** @var RegisteredBlock[] */ 
     35  protected $registered_blocks = array(); 
     36  /** @var DisplayBlock[] */ 
    2637  protected $display_blocks = array(); 
    2738 
    28   public function BlockManager($id) 
     39  /** 
     40   * @param string $id 
     41   */ 
     42  public function __construct($id) 
    2943  { 
    3044    $this->id = $id; 
    3145  } 
    3246 
    33   /** triggers an action that allows implementors of menu blocks to register the blocks*/ 
     47  /** 
     48   * Triggers a notice that allows plugins of menu blocks to register the blocks. 
     49   */ 
    3450  public function load_registered_blocks() 
    3551  { 
    36     trigger_action('blockmanager_register_blocks', array(&$this) ); 
    37   } 
    38  
     52    trigger_action('blockmanager_register_blocks', array(&$this)); 
     53  } 
     54   
     55  /** 
     56   * @return string 
     57   */ 
    3958  public function get_id() 
    4059  { 
     
    4261  } 
    4362 
     63  /** 
     64   * @return RegisteredBlock[] 
     65   */ 
    4466  public function get_registered_blocks() 
    4567  { 
     
    4769  } 
    4870 
    49   /** registers a block with this menu. usually called as a result of menubar_register_blocks action 
    50    * @param MenuBlock block 
    51   */ 
     71  /** 
     72   * Add a block with the menu. Usually called in 'blockmanager_register_blocks' event. 
     73   * 
     74   * @param RegisteredBlock &$block 
     75   */ 
    5276  public function register_block(&$block) 
    5377  { 
    54     if ( isset($this->registered_blocks[$block->get_id()] ) ) 
     78    if (isset($this->registered_blocks[$block->get_id()])) 
    5579    { 
    5680      trigger_error("Block '".$block->get_id()."' is already registered", E_USER_WARNING); 
     
    6185  } 
    6286 
    63   /** performs one time preparation of registered blocks for display; 
    64    * triggers the action menubar_prepare_display where implementors can 
     87  /** 
     88   * Performs one time preparation of registered blocks for display. 
     89   * Triggers 'blockmanager_prepare_display' event where plugins can 
    6590   * reposition or hide blocks 
    66   */ 
     91   */ 
    6792  public function prepare_display() 
    6893  { 
     
    7095    $conf_id = 'blk_'.$this->id; 
    7196    $mb_conf = isset($conf[$conf_id]) ? $conf[$conf_id] : array(); 
    72     if ( !is_array($mb_conf) ) 
     97    if (!is_array($mb_conf)) 
     98    { 
    7399      $mb_conf = @unserialize($mb_conf); 
     100    } 
    74101 
    75102    $idx = 1; 
    76     foreach( $this->registered_blocks as $id => $block ) 
    77     { 
    78       $pos = isset( $mb_conf[$id] ) ? $mb_conf[$id] : $idx*50; 
    79       if ( $pos>0 ) 
     103    foreach ($this->registered_blocks as $id => $block) 
     104    { 
     105      $pos = isset($mb_conf[$id]) ? $mb_conf[$id] : $idx*50; 
     106      if ($pos>0) 
    80107      { 
    81108        $this->display_blocks[$id] = new DisplayBlock($block); 
     
    85112    } 
    86113    $this->sort_blocks(); 
    87     trigger_action( 'blockmanager_prepare_display', array(&$this) ); 
     114    trigger_action('blockmanager_prepare_display', array(&$this)); 
    88115    $this->sort_blocks(); 
    89116  } 
    90117 
    91   /** returns true if the block whose id is hidden 
    92    * @param string block_id 
    93   */ 
     118  /** 
     119   * Returns true if the block is hidden. 
     120   * 
     121   * @param string $block_id 
     122   * @return bool 
     123   */ 
    94124  public function is_hidden($block_id) 
    95125  { 
    96     return isset($this->display_blocks[$block_id]) ? false : true; 
    97   } 
    98  
     126    return !isset($this->display_blocks[$block_id]); 
     127  } 
     128 
     129  /** 
     130   * Remove a block from the displayed blocks. 
     131   * 
     132   * @param string $block_id 
     133   */ 
    99134  public function hide_block($block_id) 
    100135  { 
    101     unset( $this->display_blocks[$block_id] ); 
    102   } 
    103  
     136    unset($this->display_blocks[$block_id]); 
     137  } 
     138 
     139  /** 
     140   * Returns a visible block. 
     141   * 
     142   * @param string $block_id 
     143   * @return &DisplayBlock|null 
     144   */ 
    104145  public function &get_block($block_id) 
    105146  { 
    106147    $tmp = null; 
    107     if ( isset($this->display_blocks[$block_id]) ) 
     148    if (isset($this->display_blocks[$block_id])) 
    108149    { 
    109150      return $this->display_blocks[$block_id]; 
     
    112153  } 
    113154 
     155  /** 
     156   * Changes the position of a block. 
     157   * 
     158   * @param string $block_id 
     159   * @param int $position 
     160   */ 
    114161  public function set_block_position($block_id, $position) 
    115162  { 
    116     if ( isset($this->display_blocks[$block_id]) ) 
     163    if (isset($this->display_blocks[$block_id])) 
    117164    { 
    118165      $this->display_blocks[$block_id]->set_position($position); 
     
    120167  } 
    121168 
     169  /** 
     170   * Sorts the blocks. 
     171   */ 
    122172  protected function sort_blocks() 
    123173  { 
    124     uasort( $this->display_blocks, array('BlockManager', 'cmp_by_position') ); 
    125   } 
    126  
     174    uasort($this->display_blocks, array('BlockManager', 'cmp_by_position')); 
     175  } 
     176 
     177  /** 
     178   * Callback for blocks sorting. 
     179   */ 
    127180  static protected function cmp_by_position($a, $b) 
    128181  { 
     
    130183  } 
    131184 
     185  /** 
     186   * Parse the menu and assign the result in a template variable. 
     187   * 
     188   * @param string $var 
     189   * @param string $file 
     190   */ 
    132191  public function apply($var, $file) 
    133192  { 
     
    137196    trigger_action('blockmanager_apply', array(&$this) ); 
    138197 
    139     foreach( $this->display_blocks as $id=>$block) 
    140     { 
    141       if (empty($block->raw_content) and empty($block->template) ) 
     198    foreach ($this->display_blocks as $id=>$block) 
     199    { 
     200      if (empty($block->raw_content) and empty($block->template)) 
    142201      { 
    143202        $this->hide_block($id); 
     
    150209} 
    151210 
     211 
    152212/** 
    153  * Represents a menu block registered in a Menu object. 
     213 * Represents a menu block registered in a BlockManager object. 
    154214 */ 
    155215class RegisteredBlock 
    156216{ 
     217  /** @var string */ 
    157218  protected $id; 
     219  /** @var string */ 
    158220  protected $name; 
     221  /** @var string */ 
    159222  protected $owner; 
    160223 
    161   public function RegisteredBlock($id, $name, $owner) 
     224  /** 
     225   * @param string $id 
     226   * @param string $name 
     227   * @param string $owner 
     228   */ 
     229  public function __construct($id, $name, $owner) 
    162230  { 
    163231    $this->id = $id; 
     
    166234  } 
    167235 
    168   public function get_id() { return $this->id; } 
    169   public function get_name() { return $this->name; } 
    170   public function get_owner() { return $this->owner; } 
     236  /** 
     237   * @return string 
     238   */ 
     239  public function get_id() 
     240  { 
     241    return $this->id; 
     242  } 
     243 
     244  /** 
     245   * @return string 
     246   */ 
     247  public function get_name() 
     248  { 
     249    return $this->name; 
     250  } 
     251 
     252  /** 
     253   * @return string 
     254   */ 
     255  public function get_owner() 
     256  { 
     257    return $this->owner; 
     258  } 
    171259} 
    172260 
     261 
    173262/** 
    174  * Represents a menu block ready for display in the Menu object. 
     263 * Represents a menu block ready for display in the BlockManager object. 
    175264 */ 
    176265class DisplayBlock 
    177266{ 
     267  /** @var RegisteredBlock */ 
    178268  protected $_registeredBlock; 
     269  /** @var int */ 
    179270  protected $_position; 
    180  
     271  /** @var string */ 
    181272  protected $_title; 
    182273 
     274  /** @var mixed */ 
    183275  public $data; 
     276  /** @var string */ 
    184277  public $template; 
     278  /** @var string */ 
    185279  public $raw_content; 
    186280 
    187   public function DisplayBlock($registeredBlock) 
    188   { 
    189     $this->_registeredBlock = &$registeredBlock; 
    190   } 
    191  
    192   public function &get_block() { return $this->_registeredBlock; } 
    193  
    194   public function get_position() { return $this->_position; } 
     281  /** 
     282   * @param RegisteredBlock &$block 
     283   */ 
     284  public function __construct($block) 
     285  { 
     286    $this->_registeredBlock = &$block; 
     287  } 
     288 
     289  /** 
     290   * @return &RegisteredBlock 
     291   */ 
     292  public function &get_block() 
     293  { 
     294    return $this->_registeredBlock; 
     295  } 
     296 
     297  /** 
     298   * @return int 
     299   */ 
     300  public function get_position() 
     301  { 
     302    return $this->_position; 
     303  } 
     304 
     305  /** 
     306   * @param int $position 
     307   */ 
    195308  public function set_position($position) 
    196309  { 
     
    198311  } 
    199312 
     313  /** 
     314   * @return string 
     315   */ 
    200316  public function get_title() 
    201317  { 
    202318    if (isset($this->_title)) 
     319    { 
    203320      return $this->_title; 
     321    } 
    204322    else 
     323    { 
    205324      return $this->_registeredBlock->get_name(); 
    206   } 
    207  
     325    } 
     326  } 
     327 
     328  /** 
     329   * @param string 
     330   */ 
    208331  public function set_title($title) 
    209332  { 
  • trunk/include/menubar.inc.php

    r21817 r25762  
    2323 
    2424/** 
    25  * This file is included by the main page to show the menu bar 
    26  * 
     25 * @package functions\menubar 
    2726 */ 
    2827 
     
    3130initialize_menu(); 
    3231 
     32/** 
     33 * Setups each block the main menubar. 
     34 */  
    3335function initialize_menu() 
    3436{ 
     
    330332  $menu->apply('MENUBAR',  'menubar.tpl' ); 
    331333} 
     334 
    332335?> 
Note: See TracChangeset for help on using the changeset viewer.