Drupal 模块开发基本教程（二）

第二部分：模块的自定义页面显示方法

许多时候我们需要为一些数据显示一个自定义格式的页面。熟悉模板的同志们可能曾经失望的发现，模板只能控制除$content之外的那部分页面。在模板 里，内容区之外的其他部分你想怎么定义都行，但要控制内容的格式，对不起，它是由一个名为$content的变量一次输出了整个内容正文。

这就决定了，一般情况下，内容的格式控制只能通过模块来实现，呵呵——不会写程序的同志们可能要晕倒了；其实别的方法也不是没有，就是……通过能写模块的 人来实现，哈哈哈，这个是开玩笑哈，另一个方法是修改theme引擎来实现（这个另文阐述，放在这里离题了）。还有非标准的方法，那些个就不介绍了，会误 导群众，最后必将导致网站维护、升级异常困难等后果。

下面是一个最简单的页面显示函数，输出我们要的内容：

function example_foo() {
  $content = '<p>The quick brown fox jumps over the lazy dog.</p>';
  return $content;
}

真够简单，问题是我们该访问那个URL这个页面才会出来呢？下面drupal的url定义钩子hook_menu()隆重登场：

function example_menu($may_cache) {
  $items = array();

  // $may_cache参数用来将菜单项分为两类。
  // $may_cache 为 TRUE时返回的菜单项对当前用户在任何时候都可用（并被缓存）；
  // 其他的则是可更改的或只在一定的路径下才被定义的，例如带参数的动态路径。
  // 绝大多数模块都会有可缓存的菜单项。
  if ($may_cache) {
    // 这是你必须提供的最基本信息
    $items[] = array('path' => 'foo',
       'title' => t('foo'),
       'callback' => 'example_foo',
       'access' => TRUE);
  }

  return $items;
}

好了，现在访问http://example.com/foo，你可以看到输出的内容了……“Ooops，显示说404 not found”。这个还是有可能的，因为$may_cache的菜单项都被缓存了，新的路径还没有刷新到缓存里面，此时，要么用devel模块clear cache，要么浏览一下管理页面中的“菜单”页面就会刷新菜单路径缓存了。现在应该可以了，这样，你在example_foo()的$content里 想怎么构建你的页面都行，那个只是html+css的问题了。

顺带讲一下hook_menu()。这个hook的用法蛮灵活，复杂的导航必备，例如通过定义MENU_LOCAL_TASK类型的路径，可以在其他模块 产生的页面上的Secondary Tabs部分嵌入自己的页面。前面的例子里，我们在$items数组里用数组定义了页面的URL相对路径“path”，页面标题“title”，回调函数 “callback”和权限控制“access”，整一个意思就是告诉drupal的菜单系统“如果访问foo这个路径，那就调用example_foo 这个函数，产生的页面的标题是foo，同时允许任意用户访问（因为access始终是TRUE）”。

下面是一个带参数的url地址定义：

function example_menu($may_cache) {
  $items = array();

    // 通过使用MENU_CALLBACK类型的路径，我们可以为指定路径注册一个
    // 回调函数而不出现在菜单项列表里，管理员也不能在菜单管理里禁用这个路径
    $items[] = array('path' => 'bar/baz', 'title' => t('baz'),
      'callback' => 'example_baz',
      'access' => TRUE,
      'type' => MENU_CALLBACK);

    // 下面的菜单项没有注册回调函数，此时，属性就会从父路径继承。
    // 例如，这里也会使用父路径的权限控制。不过如果路径上有指定参数的话，
    // 我们重定义了标题。
    // 注意：如果没有'type'属性，此项会在菜单中显示，也就是说'type'不被继承。
    $items[] = array('path' => 'bar/baz/52/97',
      'title' => t('the magic numbers'),
      'type' => MENU_CALLBACK);
  }

  return $items;
}

/**
* 一个更加复杂的带参数的页面回调函数。
*
* 参数是从页面的URL中传递的。参数位于页面访问路径的后面两个元素。
* 正因为如此，如果页面的URL发生了改变，这个函数也不需要重写。
* 在这里为参数提供缺省的值是个良好的习惯，这样页面才总是可以访问的。
*/
function example_baz($alice = 0, $bob = 0) {
  // 永远不要相信URL中传来的值是安全的！一定要记得检查这些值。
  if (!is_numeric($alice) || !is_numeric($bob)) {
    // 如果参数都不是数字，我们将显示一个标准的“你无权访问”的页面
    drupal_access_denied();
    return;
  }

  $list[] = "Alice's number was $alice.";
  $list[] = "Bob's number was $bob.";
  $list[] = 'The total was '. ($alice + $bob) .'.';
  // 调用theme函数实现输出的格式化，theme_item_list()只是许多theme函数中的一个
  $content = theme('item_list', $list);
  return $content;
}

如果用户访问http://example.com/?q=bar/baz，菜单系统会执行example_baz()，如果用户访问http: //example.com/?q=bar/baz/1/2，菜单系统会首先查找bar/baz/1/2，如果找不到对应定义会接着找 bar/baz/1。如果又找不到，它就会找bar/baz，这样它就会执行example_baz(1,2)。注意路径中的数字部分作为参数传递给了函 数，这个实在是非常好用。

如果用户访问http://example.com/?q=bar/baz/52/97，菜单系统找到了匹配，但由于回调函数被省略，因此它最终调用的是 example_baz(52,97)。有什么不同呢，此时页面标题不再是“baz”，而是“the magic numbers”了。

前面所有的路径定义中access都为TRUE，但通常我们都希望对页面内容的访问作一些权限控制。此时我们需要在模块里实现hook_perm()函数：

function example_perm() {
  return array('access foo', 'access baz');
}

现在，你在“访问控制”页面就可以分配这两个权限给指定的角色了。同时，你还要在hook_menu里这样定义'access'：

'access' => user_access('access foo'),

user_access()函数会访问$user全局变量和权限设定以确定访问页面的当前用户是否有'access foo'这个权限，有就返回TRUE，没有返回FALSE。用户ID为1的用户默认拥有任何权限，即user_access(‘任意值’)对他来说都会返 回TRUE；权限管理对他完全没用，乖乖。——所以，有特殊要求时，记得还要控制uid=1的用户。

好了，我相信你已经能够用模块定义自己的页面了——虽然看似有些繁琐，但恭喜你已经迈出模块之旅的第一步。