hook_menu()钩子可以让模块来注册如何处理URL请求的路径,路径可以只使用来处理URL请求,也可以注册一个链接作为导航菜单。一个路径和它对应的信息通常被叫做“菜单路由项”(menu router item),这个钩子很少被使用(例如在新的模块被启用的时候),结果被缓存在数据库中。
hook_menu()钩子的实现通常返回一个关联数组,它的的键值就是路径,它的值就是一组相关属性的关联数组。它的返回值主要包括以下字段:
- title:必填项,菜单项的标题
- title callback:用来创建标题的回调函数,默认使用t()函数翻译,如果想使用原字符,设置为false
- title arguments:传递给t()函数的参数或者自定义的回调函数
- description:菜单项的说明
-
page callback:用户访问URL地址时显示页面的回调函数,如果未设置,则使用父菜单项的回调函数。例如我们设置了菜单项bar/foo
<code>
function test_menu() { $items['bar/foo'] = array( 'page callback' => 'test_abc_view', ); return $items; } function test_abc_view($ghi = 0, $jkl = '') { // ... }
</code> 当请求url路径‘bar/foo’时,回调函数test_abc_view被执行,参数$ghi和$jkl使用默认参数值。 当请求url路径‘bar/foo/123/456’时,回调函数test_abc_view被执行,参数$ghi的值为123,而$jkl的值为456,这个参数是自动从url串中获取并传递给回调函数。
-
page arguments:传递给page callback的一个数组。
-
delivery callback:用于打包和发送结果到page callback函数和浏览器的回调函数,默认值为drupal函数drupal_deliver_html_page(),除非是一个从父菜单继承的值(此处不太明白)。值得注意的是,这个回调函数在访问权限验证失败的情况下也会执行,所以我们在定义这个回调函数时要考虑到这点。
-
access callback:访问权限控制的回调函数,返回TRUE表示用户有权限访问该菜单项,返回FALSE则没有权限访问。也可以是一个布尔常量或数字来代替回调函数。默认为drupal函数user_access()。
-
access arguments:传递给access callbac回调函数的数组参数。如果回调函数是从父菜单项继承的,则该参数也会从父菜单继承,除非在子菜单中定义覆盖继承的值。
-
theme callback:可选。返回drupal系统中存在的机器可读的主题的名称,若没有提供,则从父菜单中继承。如果没有定义该回调函数或者该函数没有返回当前drupal中定义的可用的主题,则由drupal函数hook_custom_theme()或者默认主题决定。一般情况下,这个回调函数主要用于那些和特定主题紧密相关的页面(比如一个模块允许根据用户的角色动态的设置主题)。
-
theme arguments:传递给theme callback回调函数的数组。
-
file:定义page callback函数的文件,在调用时要包含进来。这个应该设置为相对于当前模块 的路径。这个值只适用于page callback,不适用于其他回调函数。
-
file path:定义上述file参数文件所在的路径。
-
load arguments:传递给通配符对象加载器的数组参数。例如,一个模块注册了一个路径‘node/%node/revisions/%/view’,该参数设置为array(3),‘%node’表示使用node_load()加载函数来加载页面,参数中的3表示把路径中第4段传递给node_load()(数字索引从0开始),因此,如果请求路径‘node/12/revisions/29/view’,则会调用node_load(12,29)。
-
weight:数字,用于判断在菜单项中显示位置,数字越大, 显示的位置越靠下,默认值为0,如果权重值一样,则按照字母顺序排列。
-
menu_name:可选。如果不想该菜单项显示在导航中可以设置该项。
-
expanded:可选。如果设置为TRUE,并且提供了菜单链接,那么这个菜单链接始终是展开显示的,跟在UI管理界面中设置复选框为勾选的效果是一样的。
-
context:可选。定义标签(tab)显示的上下文。所有的标签都默认显示为本地任务(local tasks)在页面上下文中。包括:
MENU_CONTEXT_PAGE:(默认)在页面上下文中标签显示为本地任务。 MENU_CONTEXT_INLIME:标签在页面上下文外只显示为上下文链接。
-
tab_parent:对于本地任务菜单项,设置为本地任务菜单的父菜单项,默认为该路径中去除最后一项的值,比如‘admin/people/create’的父菜单项为‘admin/people’。
-
tab_root:对于本地任务来说,该项为最近的非标签项的值,同tab_parent。
-
position:在系统管理菜单中显示的位置,可选为left或right。
-
type:描述菜单项属性的位掩码,这些位掩码在menu.inc定义:
- MENU_NORMAL_ITEM:普通菜单项显示在菜单树中,而且可以被管理员移动或隐藏。
- MENU_CALLBACK:回调函数注册一个URL路径,从而当URL路径被访问时产生正确的信息。
- MENU_SUGGESTED_ITEM:建议菜单,管理员启用后将变为MENU_NORMAL_ITEM
- MENU_LOCAL_ACTION:本地动作是描述父菜单项比如添加一个用户或区块的动作,在主题的动作列表中显示
- MENU_LOCAL_TASK:本地任务是描述显示不同数据的菜单项,一般显示为标签(tabs)
- MENU_DEFAULT_LOCAL_TASK:一组本地任务中设置为默认显示的项。
-
options:当从菜单项中创建链接时传递给l()函数的选项数组。