Changeset 25762 for trunk/include


Ignore:
Timestamp:
Dec 1, 2013, 4:03:38 PM (10 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.