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;

}

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的用户。

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