From a5e048a5fd3b3f45fad4a94003d225d6f0401748 Mon Sep 17 00:00:00 2001
From: Dries Buytaert <dries@buytaert.net>
Date: Sun, 28 Sep 2003 11:08:17 +0000
Subject: [PATCH] - Renamed some menu items for clarity and ... added basic
 phpDoc comments.

---
 includes/menu.inc    | 188 +++++++++++++++++++++++++------------------
 modules/admin.module |   4 +-
 2 files changed, 110 insertions(+), 82 deletions(-)

diff --git a/includes/menu.inc b/includes/menu.inc
index 9a5e21fd38e..99a298f434f 100644
--- a/includes/menu.inc
+++ b/includes/menu.inc
@@ -2,7 +2,7 @@
 // $Id$
 
 /**
- * Register a menu item to the menu system.
+ * Register a menu item with the menu system.
  */
 function menu($path, $title, $callback = NULL, $help = NULL, $weight = 0, $hidden = 0) {
   global $_list;
@@ -11,10 +11,29 @@ function menu($path, $title, $callback = NULL, $help = NULL, $weight = 0, $hidde
   $_list[$path] = array("title" => $title, "callback" => $callback, "help" => $help, "weight" => $weight, "hidden" => $hidden);
 }
 
+/**
+ * Returns an array with the menu items that lead to the specied path.
+ */
+function menu_get_trail($path) {
+  global $_list;
+
+  $trail = array();
+
+  while ($path) {
+    if ($_list[$path]) {
+      array_unshift($trail, $path);
+    }
+
+    $path = substr($path, 0, strrpos($path, "/"));
+  }
+
+  return $trail;
+}
+
 /**
  * Returns the path of the active menu item.
  */
-function menu_get_active() {
+function menu_get_active_item() {
   global $_list;
   static $path;
 
@@ -29,109 +48,51 @@ function menu_get_active() {
   return $path;
 }
 
-function menu_get_path($path) {
-  global $_list;
-  static $trail; // cache
-
-  if (empty($trail)) {
-    $trail = array();
-
-    while ($path) {
-      if ($_list[$path]) {
-        array_unshift($trail, $path);
-      }
-
-      $path = substr($path, 0, strrpos($path, "/"));
-    }
-  }
-
-  return $trail;
-}
-
+/**
+* Returns the title of the active menu item.
+*/
 function menu_get_active_title() {
   global $_list;
 
-  if ($path = menu_get_active()) {
+  if ($path = menu_get_active_item()) {
     return ucfirst($_list[$path]["title"]);
   }
 }
 
+/**
+* Returns the help associated with the active menu item.
+*/
 function menu_get_active_help() {
   global $_list;
 
-  if ($path = menu_get_active()) {
+  if ($path = menu_get_active_item()) {
     return $_list[$path]["help"];
   }
 }
 
-function menu_is_active($path) {
-
-}
-
-function menu_render_item($path) {
-  global $_list;
-
-  if ($path == $_GET["q"]) {
-    $css = " class=\"active\"";
-  }
-
-  return "<a href=\"". url($path) ."\"$css>". t($_list[$path]["title"]) ."</a>";
-}
-
-function menu_active_breadcrumb() {
+/**
+ * Returns an array of rendered menu items in the active breadcrumb trail.
+ */
+function menu_get_active_breadcrumb() {
 
   $links[] = l(t("Home"), "");
 
-  $trail = menu_get_path($_GET["q"]);
+  $trail = menu_get_trail($_GET["q"]);
   foreach ($trail as $item) {
-    $links[] = menu_render_item($item);
+    $links[] = _render_item($item);
   }
 
   return $links;
 }
 
-function _menu_sort($a, $b) {
+
+/**
+ * Execute the handler associated with the active menu item.
+ */
+function menu_execute_active_handler() {
   global $_list;
 
-  $a = &$_list[$a];
-  $b = &$_list[$b];
-
-  return $a["weight"] < $b["weight"] ? -1 : ($a["weight"] > $b["weight"] ? 1 : ($a["title"] < $b["title"] ? -1 : 1));
-}
-
-function menu_tree($parent = "") {
-  global $_list;
-  static $trail;
-
-  if (empty($tail)) {
-    $trail = menu_get_path($_GET["q"]);
-  }
-
-  if ($_list[$parent]["children"]) {
-    $output = "\n<ul>\n";
-    usort($_list[$parent]["children"], "_menu_sort");
-    foreach ($_list[$parent]["children"] as $item) {
-      if ($_list[$item]["hidden"] == 0) {
-        $style = ($_list[$item]["children"] ? (in_array($item, $trail)  ? "expanded" : "collapsed") : "leaf");
-        $output .= "<li class=\"$style\">";
-        $output .= menu_render_item($item);
-        if (in_array($item, $trail)) {
-          $output .= menu_tree($item);
-        }
-        $output .= "</li>\n";
-      }
-    }
-    $output .= "</ul>\n";
-  }
-
-  return $output;
-}
-
-
-function menu_execute_action() {
-  global $_list;
-
-  $path = menu_get_active();
+  $path = menu_get_active_item();
 
   if ($_list[$path]["callback"]) {
     $arg = substr($_GET["q"], strlen($path) + 1);
@@ -144,6 +105,53 @@ function menu_execute_action() {
   }
 }
 
+/**
+ * Returns true when the path is in the active trail.
+ */
+function menu_in_active_trail($path) {
+  static $trail;
+
+  if (empty($trail)) {
+    $trail = menu_get_trail($_GET["q"]);
+  }
+
+  return in_array($path, $trail);
+}
+
+/**
+ * Returns a rendered menu tree.
+ */
+function menu_tree($parent = "") {
+  global $_list;
+  static $trail;
+
+  if (empty($tail)) {
+    $trail = menu_get_trail($_GET["q"]);
+  }
+
+  if ($_list[$parent]["children"]) {
+    $output = "\n<ul>\n";
+    usort($_list[$parent]["children"], "_menu_sort");
+    foreach ($_list[$parent]["children"] as $item) {
+      if ($_list[$item]["hidden"] == 0) {
+        $style = ($_list[$item]["children"] ? (menu_in_active_trail($item)  ? "expanded" : "collapsed") : "leaf");
+        $output .= "<li class=\"$style\">";
+        $output .= _render_item($item);
+        if (menu_in_active_trail($item, $trail)) {
+          $output .= menu_tree($item);
+        }
+        $output .= "</li>\n";
+      }
+    }
+    $output .= "</ul>\n";
+  }
+
+  return $output;
+}
+
+/**
+ * Query to module to build the menu.
+ */
 function menu_build($type) {
   /*
   ** Build a sequential list of all menus items.
@@ -175,4 +183,24 @@ function menu_build($type) {
   }
 }
 
+function _menu_sort($a, $b) {
+  global $_list;
+
+  $a = &$_list[$a];
+  $b = &$_list[$b];
+
+  return $a["weight"] < $b["weight"] ? -1 : ($a["weight"] > $b["weight"] ? 1 : ($a["title"] < $b["title"] ? -1 : 1));
+}
+
+function _render_item($path) {
+  global $_list;
+
+  if ($path == $_GET["q"]) {
+    $css = " class=\"active\"";
+  }
+
+  return "<a href=\"". url($path) ."\"$css>". t($_list[$path]["title"]) ."</a>";
+}
+
+
 ?>
diff --git a/modules/admin.module b/modules/admin.module
index 3bba6845649..19a1baad4e8 100644
--- a/modules/admin.module
+++ b/modules/admin.module
@@ -47,14 +47,14 @@ function admin_page() {
       $contents = "<small>$help</small><hr />";
     }
     if (arg(1)) {
-      $contents .= menu_execute_action();
+      $contents .= menu_execute_active_handler();
     }
     else {
       $contents.= watchdog_overview("actions");
       $title = t("System messages");
     }
 
-    $breadcrumb = menu_active_breadcrumb();
+    $breadcrumb = menu_get_active_breadcrumb();
     array_pop($breadcrumb);
     $title = menu_get_active_title();