第二部分:模块的自定义页面显示方法
许多时候我们需要为一些数据显示一个自定义格式的页面。熟悉模板的同志们可能曾经失望的发现,模板只能控制除$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的用户。
好了,我相信你已经能够用模块定义自己的页面了——虽然看似有些繁琐,但恭喜你已经迈出模块之旅的第一步。