inc/MenuSet.php

   1 <?php
   2 /**
   3 * Some intelligence and standardisation around presenting a menu hierarchy.
   4 *
   5 * See the MenuSet class for examples as that is the primary interface.
   6 * @see MenuSet
   7 *
   8 * @package awl
   9 * @subpackage   MenuSet
  10 * @author    Andrew McMillan <andrew@mcmillan.net.nz>
  11 * @copyright Catalyst IT Ltd, Morphoss Ltd <http://www.morphoss.com/>
  12 * @license   http://gnu.org/copyleft/gpl.html GNU GPL v2
  13 */
  14 require_once("AWLUtilities.php");
  15
  16 /**
  17 * Each menu option is an object.
  18 * @package awl
  19 */
  20 class MenuOption {
  21   /**#@+
  22   * @access private
  23   */
  24   /**
  25   * The label for the menu item
  26   * @var string
  27   */
  28   var $label;
  29
  30   /**
  31   * The target URL for the menu
  32   * @var string
  33   */
  34   var $target;
  35
  36   /**
  37   * The title for the item when moused over, which should be displayed as a tooltip.
  38   * @var string
  39   */
  40   var $title;
  41
  42   /**
  43   * Whether the menu option is active
  44   * @var string
  45   */
  46   var $active;
  47
  48   /**
  49   * For sorting menu options
  50   * @var string
  51   */
  52   var $sortkey;
  53
  54   /**
  55   * Style to render the menu option with.
  56   * @var string
  57   */
  58   var $style;
  59
  60   /**
  61   * The MenuSet that this menu is a parent of
  62   * @var string
  63   */
  64   var $submenu_set;
  65   /**#@-*/
  66
  67   /**
  68   * A reference to this menu option itself
  69   * @var reference
  70   */
  71   var $self;
  72
  73   /**#@+
  74   * @access public
  75   */
  76   /**
  77   * The rendered HTML fragment (once it has been).
  78   * @var string
  79   */
  80   var $rendered;
  81   /**#@-*/
  82
  83   /**
  84   * The thing we click
  85   * @param string $label The label to display for this option.
  86   * @param string $target The URL to target for this option.
  87   * @param string $title Some tooltip help for the title tag.
  88   * @param string $style A base class name for this option.
  89   * @param int $sortkey An (optional) value to allow option ordering.
  90   */
  91   function MenuOption( $label, $target, $title="", $style="menu", $sortkey=1000 ) {
  92     $this->label  = $label;
  93     $this->target = $target;
  94     $this->title  = $title;
  95     $this->style  = $style;
  96     $this->attributes = array();
  97     $this->active = false;
  98     $this->sortkey = $sortkey;
  99
 100     $this->rendered = "";
 101     $this->self  =& $this;
 102   }
 103
 104   /**
 105   * Convert the menu option into an HTML string
 106   * @return string The HTML fragment for the menu option.
 107   */
 108   function Render( ) {
 109     $r = sprintf('<a href="%s" class="%s" title="%s"%s>%s</a>',
 110             $this->target, $this->style, htmlspecialchars($this->title), "%%attributes%%",
 111             htmlspecialchars($this->label), $this->style );
 112
 113     // Now process the generic attributes
 114     $attribute_values = "";
 115     foreach( $this->attributes AS $k => $v ) {
 116       if ( substr($k, 0, 1) == '_' ) continue;
 117       $attribute_values .= " $k=\"".htmlspecialchars($v)."\"";
 118     }
 119     $r = str_replace( '%%attributes%%', $attribute_values, $r );
 120
 121     $this->rendered = $r;
 122     return "$r";
 123   }
 124
 125   /**
 126   * Set arbitrary attributes of the menu option
 127   * @param string $attribute An arbitrary attribute to be set in the hyperlink.
 128   * @param string $value A value for this attribute.
 129   */
 130   function Set( $attribute, $value ) {
 131     $this->attributes[$attribute] = $value;
 132   }
 133
 134   /**
 135   * Mark it as active, with a fancy style to distinguish that
 136   * @param string $style A style used to highlight that the option is active.
 137   */
 138   function Active( $style=false ) {
 139     $this->active = true;
 140     if ( $style ) $this->style = $style;
 141   }
 142
 143   /**
 144   * This menu option is now promoted to the head of a tree
 145   */
 146   function AddSubmenu( &$submenu_set ) {
 147     $this->submenu_set = &$submenu_set;
 148   }
 149
 150   /**
 151   * Whether this option is currently active.
 152   * @return boolean The value of the active flag.
 153   */
 154   function IsActive( ) {
 155     return ( $this->active );
 156   }
 157
 158   /**
 159   * Whether this option is currently active.
 160   * @return boolean The value of the active flag.
 161   */
 162   function MaybeActive( $test_pattern, $active_style ) {
 163     if ( is_string($test_pattern) && preg_match($test_pattern,$_SERVER['REQUEST_URI']) ) {
 164       $this->Active($active_style);
 165     }
 166     return ( $this->active );
 167   }
 168 }
 169
 170
 171 /**
 172 * _CompareMenuSequence is used in sorting the menu options into the sequence order
 173 *
 174 * @param objectref $a The first menu option
 175 * @param objectref $b The second menu option
 176 * @return int ( $a == b ? 0 ( $a > b ? 1 : -1 ))
 177 */
 178 function _CompareMenuSequence( $a, $b ) {
 179   dbg_error_log("MenuSet", ":_CompareMenuSequence: Comparing %d with %d", $a->sortkey, $b->sortkey);
 180   return ($a->sortkey - $b->sortkey);
 181 }
 182
 183
 184
 185 /**
 186 * A MenuSet is a hierarchy of MenuOptions, some of which might be
 187 * MenuSet objects themselves.
 188 *
 189 * The menu options are presented in HTML span tags, and the menus
 190 * themselves are presented inside HTML div tags.  All layout and
 191 * styling is expected to be provide by CSS.
 192 *
 193 * A non-trivial example would look something like this:
 194 *<code>
 195 *require_once("MenuSet.php");
 196 *$main_menu = new MenuSet('menu', 'menu', 'menu_active');
 197 *  ...
 198 *$other_menu = new MenuSet('submenu', 'submenu', 'submenu_active');
 199 *$other_menu->AddOption("Extra Other","/extraother.php","Submenu option to do extra things.");
 200 *$other_menu->AddOption("Super Other","/superother.php","Submenu option to do super things.");
 201 *$other_menu->AddOption("Meta Other","/metaother.php","Submenu option to do meta things.");
 202 *  ...
 203 *$main_menu->AddOption("Do This","/dothis.php","Option to do this thing.");
 204 *$main_menu->AddOption("Do That","/dothat.php","Option to do all of that.");
 205 *$main_menu->AddSubMenu( $other_menu, "Do The Other","/dotheother.php","Submenu to do all of the other things.", true);
 206 *  ...
 207 *if ( isset($main_menu) && is_object($main_menu) ) {
 208 *  $main_menu->AddOption("Home","/","Go back to the home page");
 209 *  echo $main_menu->Render();
 210 *}
 211 *</code>
 212 * In a hierarchical menu tree, like the example above, only one sub-menu will be
 213 * shown, which will be the first one that is found to have active menu options.
 214 *
 215 * The menu display will generally recognise the current URL and mark as active the
 216 * menu option that matches it, but in some cases it might be desirable to force one
 217 * or another option to be marked as active using the appropriate parameter to the
 218 * AddOption or AddSubMenu call.
 219 * @package awl
 220 */
 221 class MenuSet {
 222   /**#@+
 223   * @access private
 224   */
 225   /**
 226   * CSS style to use for the div around the options
 227   * @var string
 228   */
 229   var $div_id;
 230
 231   /**
 232   * CSS style to use for normal menu option
 233   * @var string
 234   */
 235   var $main_class;
 236
 237   /**
 238   * CSS style to use for active menu option
 239   * @var string
 240   */
 241   var $active_class;
 242
 243   /**
 244   * An array of MenuOption objects
 245   * @var array
 246   */
 247   var $options;
 248
 249   /**
 250   * Any menu option that happens to parent this set
 251   * @var reference
 252   */
 253   var $parent;
 254
 255   /**
 256   * The sortkey used by any previous option
 257   * @var last_sortkey
 258   */
 259   var $last_sortkey;
 260
 261   /**
 262   * Will be set to true or false when we link active sub-menus, but will be
 263   * unset until we do that.
 264   * @var reference
 265   */
 266   var $has_active_options;
 267   /**#@-*/
 268
 269   /**
 270   * Start a new MenuSet with no options.
 271   * @param string $div_id An ID for the HTML div that the menu will be presented in.
 272   * @param string $main_class A CSS class for most menu options.
 273   * @param string $active_class A CSS class for active menu options.
 274   */
 275   function MenuSet( $div_id, $main_class = '', $active_class = 'active' ) {
 276     $this->options = array();
 277     $this->main_class = $main_class;
 278     $this->active_class = $active_class;
 279     $this->div_id = $div_id;
 280   }
 281
 282   /**
 283   * Add an option, which is a link.
 284   * The call will attempt to work out whether the option should be marked as
 285   * active, and will sometimes get it wrong.
 286   * @param string $label A Label for the new menu option
 287   * @param string $target The URL to target for this option.
 288   * @param string $title Some tooltip help for the title tag.
 289   * @param string $active Whether this option should be marked as Active.
 290   * @param int $sortkey An (optional) value to allow option ordering.
 291   * @return mixed A reference to the MenuOption that was added, or false if none were added.
 292   */
 293   function &AddOption( $label, $target, $title="", $active=false, $sortkey=null ) {
 294     if ( !isset($sortkey) ) {
 295       $sortkey = (isset($this->last_sortkey) ? $this->last_sortkey + 100 : 1000);
 296     }
 297     $this->last_sortkey = $sortkey;
 298     if ( version_compare(phpversion(), '5.0') < 0) {
 299       $new_option =& new MenuOption( $label, $target, $title, $this->main_class, $sortkey );
 300     }
 301     else {
 302       $new_option = new MenuOption( $label, $target, $title, $this->main_class, $sortkey );
 303     }
 304     if ( ($old_option = $this->_OptionExists( $label )) === false ) {
 305       $this->options[] = &$new_option ;
 306     }
 307     else {
 308       dbg_error_log("MenuSet",":AddOption: Replacing existing option # $old_option ($label)");
 309       $this->options[$old_option] = &$new_option;  // Overwrite the existing option
 310     }
 311     if ( is_bool($active) && $active == false && $_SERVER['REQUEST_URI'] == $target ) {
 312       // If $active is not set, then we look for an exact match to the current URL
 313       $new_option->Active( $this->active_class );
 314     }
 315     else if ( is_bool($active) && $active ) {
 316       // When active is specified as a boolean, the recognition has been done externally
 317       $new_option->Active( $this->active_class );
 318     }
 319     else if ( is_string($active) && preg_match($active,$_SERVER['REQUEST_URI']) ) {
 320       // If $active is a string, then we match the current URL to that as a Perl regex
 321       $new_option->Active( $this->active_class );
 322     }
 323     return $new_option ;
 324   }
 325
 326   /**
 327   * Add an option, which is a submenu
 328   * @param object &$submenu_set A reference to a menu tree
 329   * @param string $label A Label for the new menu option
 330   * @param string $target The URL to target for this option.
 331   * @param string $title Some tooltip help for the title tag.
 332   * @param string $active Whether this option should be marked as Active.
 333   * @param int $sortkey An (optional) value to allow option ordering.
 334   * @return mixed A reference to the MenuOption that was added, or false if none were added.
 335   */
 336   function &AddSubMenu( &$submenu_set, $label, $target, $title="", $active=false, $sortkey=2000 ) {
 337     $new_option =& $this->AddOption( $label, $target, $title, $active, $sortkey );
 338     $submenu_set->parent = &$new_option ;
 339     $new_option->AddSubmenu( $submenu_set );
 340     return $new_option ;
 341   }
 342
 343   /**
 344   * Does the menu have any options that are active.
 345   * Most likely used so that we can then set the parent menu as active.
 346   * @param string $label A Label for the new menu option
 347   * @return boolean Whether the menu has options that are active.
 348   */
 349   function _HasActive( ) {
 350     if ( isset($this->has_active_options) ) {
 351       return $this->has_active_options;
 352     }
 353     foreach( $this->options AS $k => $v ) {
 354       if ( $v->IsActive() ) {
 355         $rc = true;
 356         return $rc;
 357       }
 358     }
 359     $rc = false;
 360     return $rc;
 361   }
 362
 363   /**
 364   * Find out how many options the menu has.
 365   * @return int The number of options in the menu.
 366   */
 367   function Size( ) {
 368     return count($this->options);
 369   }
 370
 371   /**
 372   * See if a menu already has this option
 373   * @return boolean Whether the option already exists in the menu.
 374   */
 375   function _OptionExists( $newlabel ) {
 376     $rc = false;
 377     foreach( $this->options AS $k => $v ) {
 378       if ( $newlabel == $v->label ) return $k;
 379     }
 380     return $rc;
 381   }
 382
 383   /**
 384   * Mark each MenuOption as active that has an active sub-menu entry.
 385   *
 386   * Currently needs to be called manually before rendering but
 387   * really should probably be called as part of the render now,
 388   * and then this could be a private routine.
 389   */
 390   function LinkActiveSubMenus( ) {
 391     $this->has_active_options = false;
 392     foreach( $this->options AS $k => $v ) {
 393       if ( isset($v->submenu_set) && $v->submenu_set->_HasActive() ) {
 394         // Note that we need to do it this way, since $v is a copy, not a reference
 395         $this->options[$k]->Active( $this->active_class );
 396         $this->has_active_options = true;
 397       }
 398     }
 399   }
 400
 401   /**
 402   * Mark each MenuOption as active that has an active sub-menu entry.
 403   *
 404   * Currently needs to be called manually before rendering but
 405   * really should probably be called as part of the render now,
 406   * and then this could be a private routine.
 407   */
 408   function MakeSomethingActive( $test_pattern ) {
 409     if ( $this->has_active_options ) return;  // Already true.
 410     foreach( $this->options AS $k => $v ) {
 411       if ( isset($v->submenu_set) && $v->submenu_set->_HasActive() ) {
 412         // Note that we need to do it this way, since $v is a copy, not a reference
 413         $this->options[$k]->Active( $this->active_class );
 414         $this->has_active_options = true;
 415         return $this->has_active_options;
 416       }
 417     }
 418
 419     foreach( $this->options AS $k => $v ) {
 420       if ( isset($v->submenu_set) && $v->submenu_set->MakeSomethingActive($test_pattern) ) {
 421         // Note that we need to do it this way, since $v is a copy, not a reference
 422         $this->options[$k]->Active( $this->active_class );
 423         $this->has_active_options = true;
 424         return $this->has_active_options;
 425       }
 426       else {
 427         if ( $this->options[$k]->MaybeActive( $test_pattern, $this->active_class ) ) {
 428           $this->has_active_options = true;
 429           return $this->has_active_options;
 430         }
 431       }
 432     }
 433     return false;
 434   }
 435
 436   /**
 437   * _CompareSequence is used in sorting the menu options into the sequence order
 438   *
 439   * @param objectref $a The first menu option
 440   * @param objectref $b The second menu option
 441   * @return int ( $a == b ? 0 ( $a > b ? 1 : -1 ))
 442   */
 443   function _CompareSequence( $a, $b ) {
 444     dbg_error_log("MenuSet",":_CompareSequence: Comparing %d with %d", $a->sortkey, $b->sortkey);
 445     return ($a->sortkey - $b->sortkey);
 446   }
 447
 448
 449   /**
 450   * Render the menu tree to an HTML fragment.
 451   *
 452   * @param boolean $submenus_inline Indicate whether to render the sub-menus within
 453   *   the menus, or render them entirely separately after we finish rendering the
 454   *   top level ones.
 455   * @return string The HTML fragment.
 456   */
 457   function Render( $submenus_inline = false ) {
 458     if ( !isset($this->has_active_options) ) {
 459       $this->LinkActiveSubMenus();
 460     }
 461     $options = $this->options;
 462     usort($options,"_CompareMenuSequence");
 463     $render_sub_menus = false;
 464     $r = "<div id=\"$this->div_id\">\n";
 465     foreach( $options AS $k => $v ) {
 466       $r .= $v->Render();
 467       if ( $v->IsActive() && isset($v->submenu_set) && $v->submenu_set->Size() > 0 ) {
 468         $render_sub_menus = $v->submenu_set;
 469         if ( $submenus_inline )
 470           $r .= $render_sub_menus->Render();
 471       }
 472     }
 473     $r .="</div>\n";
 474     if ( !$submenus_inline && $render_sub_menus != false ) {
 475       $r .= $render_sub_menus->Render();
 476     }
 477     return $r;
 478   }
 479
 480
 481   /**
 482   * Render the menu tree to an HTML fragment.
 483   *
 484   * @param boolean $submenus_inline Indicate whether to render the sub-menus within
 485   *   the menus, or render them entirely separately after we finish rendering the
 486   *   top level ones.
 487   * @return string The HTML fragment.
 488   */
 489   function RenderAsCSS( $depth = 0, $skip_empty = true ) {
 490     $this->LinkActiveSubMenus();
 491
 492     if ( $depth > 0 )
 493       $class = "submenu" . $depth;
 494     else
 495       $class = "menu";
 496
 497     $options = $this->options;
 498     usort($options,"_CompareMenuSequence");
 499
 500     $r = "<div id=\"$this->div_id\" class=\"$class\">\n<ul>\n";
 501     foreach( $options AS $k => $v ) {
 502       if ( $skip_empty && isset($v->submenu_set) && $v->submenu_set->Size() < 1 ) continue;
 503       $r .= "<li>".$v->Render();
 504       if ( isset($v->submenu_set) && $v->submenu_set->Size() > 0 ) {
 505         $r .= $v->submenu_set->RenderAsCSS($depth+1);
 506       }
 507       $r .= "</li>\n";
 508     }
 509     $r .="</ul></div>\n";
 510     return $r;
 511   }
 512 }