Navigation API  导航API

目录

1. 概述

2. 什么是导航

3. 导航不是什么

4. 导航如何工作

5. 导航扩展

  5.1代码扩展

     5.1.1 导航

     5.1.2 设置导航

     5.1.3 导航条 （面包屑）

  5.2 回调插件

   5.2.1 模块

   5.2.2 课程格式

   5.2.3 课程报表

   5.2.4 本地插件

1. 概述

导航 API在 Moodle 中使用多类系统导航.

2. 什么是导航

他是十分重要的去准确弄明白Moodle中的导航 .  Moodle 2.0 的目标就是规范整个moodle站点的导航结构. 导航可以通过页面对象 $PAGE, 对应于您设置页面标题部分, title部分, 任何必要的 JavaScript , 等等. 导航的结构使用信息 $PAGE 包含继承站点的导航结构. 导航或设置 blocks 是对moodle创建导航结构的解释.

导航的结构可以通过三个变量来展现:

$PAGE->navigation

这是最主要的导航结构, 它包含了所有允许用户在其他页面浏览的项目.

$PAGE->settingsnav 

设置导航结构允许用户可编辑的导航项目.

$PAGE->navbar 

这个用来设置页面的面包屑.

1. 导航不是什么

导航不是导航模块或设置模块! 这两个模块是用来创建显示导航结构的. 导航模块可以参考 $PAGE->navigation, 设置模块可以参考 $PAGE->settingsnav. 两个模块解释它们的数据成HTML并被渲染.

1. 导航是后台显示的结构没有直接调用的显示方法.

2. 导航和设置模块显示后端的导航模块，但是不能添加.

在MVC模式中, $PAGE->navigation, $PAGE->settingsnav, 和 $PAGE->navbar 是模型, 而块是视图.

 navbar 仅仅是活动的导航或设置项目的路径. navbar 不会显示在一个模块中; 代替他的是添加在主题布局文件（layout） 和显示通过核心渲染(config.php/render.php).

4. 导航如何工作

主要的导航结构通过设置 $PAGE->navigation. 导航和设置是用户查看的上下文相关的页面. 他们通过 $PAGE 对象的其他属性进行展示:

· $PAGE->context 是一个 Moodle 的上下文能力及标出用户查看的上下文页面结构.

· $PAGE->course 用户正在查看的课程. 他是十分必要的如果上下文是 CONTEXT_COURSE 或 更大. 然而, 他也是十分有用的在其他上下文中 像 CONTEXT_USER.

· $PAGE->cm 是课程模块的实例化. 他是十分必要的如果上下文是CONTEXT_MODULE 或者更大.

· $PAGE->url 用来匹配活动导航项目.

几乎每个页面设置 $PAGE->url 通过调用 $PAGE->set_url 没有多少明确设置 context, course, 或 cm. 当你调用 require_login 伴随着 course 或 cm 它会自动调用下面的:

if ($cm) {
    $PAGE->set_cm($cm, $course); // 设置全局变量$COURSE
} else {
    $PAGE->set_course($course);// 设置全局变量$COURSE
}

一个页面只需要明确设置一个 context, course, 或 cm 在下面这些条件中:

1. require_login 没有正确调用

2. 页面使用CONTEXT_SYSTEM, CONTEXT_COURSECAT, 或 CONTEXT_USER (调用 $PAGE->set_context ).

3. 页面使用一个 course 或 cm 而且也是用了上面的一个上下文 (调用 $PAGE->set_course 或 $PAGE->set_cm ).

导航结构不能生成在 $PAGE对象设置之前. 它仅仅在他第一次使用的时候生成, 或者当一些试图访问的结构或在代码尝试添加到它. 导航初始化有特别的顺序:

1. 主导航结构

2. 设置导航部分

3. 导航条 (不是必须生成的因为它的简单内容和结构)

5. 导航扩展

  5.1代码扩展

这个方法是在代码执行中对导航做任意扩展, 他将显示在你扩展代码被调用的页面里 (你最好把它放在lib.php的一个函数里).

这儿有个例子来自 一般开发论坛: Moodle 2 - 如何为一个模块设置面包屑. 它值得一读.

     5.1.1 导航

这是扩展主导航的结构.

$previewnode = $PAGE->navigation->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $previewnode->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();

上面的几行代码是添加一个预览节点在导航的底部 然后添加一个实际事情节点给预览节点 (就像给我们的树加了一片叶子). 最后一行代码是将事情节点变成可活动节点，以便于navbar 能找到他 但是如果你给他的 URL 和当前页面的url相同，你就不必在调用，因为他会自动进行创建.

下一个扩展导航是课程导航. 那么你需要知道课程id 然后调用require_login($courseorid); 以便于课程导航加载到对应的课程.

$coursenode = $PAGE->navigation->find($courseid, navigation_node::TYPE_COURSE);
$thingnode = $coursenode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();

代码的第一行是简单的查找课程节点, 找到他我们需要提供课程id 和节点的类型 TYPE_COURSE. 我们正在做的是依赖导航生成 导航然后添加到课程.

注意Moodle 加载插件是按字母顺序. 因此插件b 能被找到通过插件 a 的添加 而不是其他的方式.

     5.1.2 设置导航

添加导航和设置导航 到导航节点是非常相似的

$settingnode = $PAGE->settingsnav->add(get_string('setting'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $settingnode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();

5.1.3 导航条 （面包屑）

这是扩展的设置导航

$PAGE->navbar->ignore_active();
$PAGE->navbar->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'));
$PAGE->navbar->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));

上面的代码告诉 navbar 忽略之前添加的面包屑,只显示现在加的两个面包屑.

  5.2 回调插件

这些特殊的函是数关于导航的查找和调用 如果他们存在于插件中的话是十分有意义的, 目前只有三种插件可以通过回调扩展导航.

理想情况是所有入口通过 "Administration / Site administration" 树可以通过修改文件 settings.php 来实现 但有时他会更容易通过admin settings 设置导航树 (比如添加链接到扩展页面).

   5.2.1 模块

模块有两种回调方法,第一种是扩展导航, 第二种是扩展设置. 他们决定用户能够查看到的导航的样子.

function {modulename}_extend_navigation(${modulename}node, $course, $module, $cm)
function {modulename}_extend_settings_navigation($settings, ${modulename}node)

 5.2.2 课程格式

课程格式都能够完全地重新定义在其中的过程中生成的导航的方式，以及本它们也有几种方法，以确保正确地产生导航.

   5.2.3 课程报表

默认情况下，报表不添加自己或任何其他的导航但有回调，可以实现允许他们这样做。

   5.2.4 本地插件

本地插件也有两种回调方法,第一种是扩展导航, 第二种是扩展设置.

function local_{pluginname}_extends_navigation(global_navigation $nav)
function local_{pluginname}_extends_settings_navigation(settings_navigation $nav, context $context)

问：我的页面放在导航里但是它不能找到他?

首先你要坚持你为这个页面设置的URL。他应该和你设置在导航里的一样. 如果不满足这两个条件, 首先你可以改变自己的url通过调用 $PAGE->set_url , 或者使用第二种方式冲在导航里的URL就像下面这样:

navigation_node::override_active_url(new moodle_url('/your/url/here.php', array('param'=>'value')));

Moodle中文API之导航API