Moodle API文档 —— Page API

发表于

Page API用于对当前的页面进行设置，包括添加javaScript脚本以及设置页面的展示方式。

概述

Page API对任何Moodle页面来说都是不可分割的一部分。它允许开发者按照他们设想的方式来对页面进行设置。通过Page API你可以对标题（title）、页面首部（heading）、导航栏（navigation）、页面布局（layout）等进行设置。

这篇文档从一个简单的例子出发，之后对如何设置页面的展示效果进行了更全面的阐述。

一个简单的例子

这个例子涉及到如何在一个活动插件（activity plugin，即课程模块插件）中进行简单的页面设置。这绝对是一个最简单的例子了，因为许多基础设置都在后台自动进行。

1
2
3
4
5
6
7
8
9
10
11
12
// File: /mod/mymodulename/view.php
require_once('../../config.php');
$cmid = required_param('id', PARAM_INT);
$cm = get_coursemodule_from_id('mymodulename', $cmid, 0, false, MUST_EXIST);
$course = $DB->get_record('course', array('id' => $cm->course), '*', MUST_EXIST);
 
require_login($course, true, $cm);
$PAGE->set_url('/mod/mymodulename/view.php', array('id' => $cm->id));
$PAGE->set_title('My modules page title');
$PAGE->set_heading('My modules page heading');
 
// The rest of your code goes below this.

我们假定你已经明白了最开始的四行代码的作用。如果你不明白它是做什么的，说明你不应该从这篇文章开始看。

那么我们就从require_login()函数开始分析，假定我们已经准备好了即将用到的course和course module对象。在你调用require_login()函数时，它会自动设置当前页面的基础信息。

在上面的代码中，由于我们向require_login()函数传入了course和course module对象，这个函数为我们做了许多关于当前页面的配置工作，它把course和course module对象传给了当前页面，设置当前页面的上下文为course modules的上下文，并且将当前的页面布局设置为incourse，即课程模块的标准布局。

我们必须要做的事情有：

  1. 设置页面的URL，这是必须的
  2. 设置当前页面的标题，即以<title>标签展示的内容
  3. 设置当前页面的页面首部，通常会使用pages header

注意：在进行页面的输出前，这些设置必须要完成。这意味着你必须在页面的header输出和实例化任何表单之前就要进行这些设置。
如果在这之前你添加了一点点输出，那么你就会得到一个已经设置好的其他模块的页面。

Moodle页面全局变量$PAGE

对每个页面你可能都要请求moodle设置多个全局的结构。例如数据库对象$DB和保存着配置文件的$CFG就是两个你可能已经意识到的全局变量。$PAGE是当前文章的焦点，是moodle_page类的对象，存储着所有的页面信息并且在展示页面的时候需要用到output库$OUTPUT。$PAGE用来设置页面，$OUTPUT用来输出页面。$PAGE包含许多内部逻辑和神奇的魔法，而$OUTPUT仅仅是用来展示的库，它除了生成HTML代码之外几乎不做什么。

页面设置

在moodle中创建页面时，你有许多事情要做。一些东西已经为你设置好了，但是并不总是这样。

URL

这绝对是必须要设置的，这个设置失败会使moodle报”url不存在”的error。

可以按照如下几种方式设置URL：

1
2
3
$PAGE->set_url(new moodle_url('/page/to/your/file.php', array('key' => 'value', 'id' => 3)));
$PAGE->set_url('/page/to/your/file.php', array('key' => 'value', 'id' => 3));
$PAGE->set_url('/page/to/your/file.php?key=value&id=3');

上面的代码列出了三种不同的设置URL的方式。我们推荐使用前面两种方式来对url进行设置，因为这种方式保证了在传递url的时候是绝对准确的。set_url()函数内部是将你传入的参数赋给一个moodle_url对象。

你传给页面的url会被许多Moodle API调用，最重要的是，它会用来为你的页面创建导航栏，因此需要你准确的对它进行设置。

上下文（Context）

这也是必须要设置的，然而在很多情况下，moodle都会自动为你进行设置。

为了给页面设置上下文，你需要提供给它一个context对象。在Moodle2.2及以上版本中，可以按照如下方式进行设置：

1
2
3
4
5
// Moodle 2.2 and greater
$PAGE->set_context(context_system::instance());
$PAGE->set_context(context_coursecat::instance($categoryid));
$PAGE->set_context(context_course::instance($courseid));
$PAGE->set_context(context_module::instance($moduleid));

在Moodle2.0+和Moodle2.1+版本中，如下代码和上述代码等价：

1
2
3
4
5
// Moodle 2.0 and 2.1
$PAGE->set_context(get_system_context());
$PAGE->set_context(get_context_instance(CONTEXT_COURSECAT, $categoryid));
$PAGE->set_context(get_context_instance(CONTEXT_COURSE, $courseid));
$PAGE->set_context(get_context_instance(CONTEXT_MODULE, $moduleid));

在上面的两个例子中，都多次进行了context的设置，然而，你应该将上下文设置为最符合当前页面的上下文。

如果这是一个插件，那么上下文应该是你用于权限检查的上下文。

正如之前提到的那样，有些时候Moodle会自动的设置上下文。

如果你的脚本调用了require_login()（大多数脚本都需要调用该函数），并且你传入了course对象或module对象，那么你不再需要再调用set_context()。这是因为require_login()已经自动的进行了处理。

如果你的脚本没有调用require_login()，或者你没有给它传入moodle对象也没有传入module对象，那么你必须自己对上下文进行设置。

可选的设置

下面是一些可选的设置，你会在Moodle中经常见到这些设置。

页面布局（page layout）

如下代码可将页面布局设为标准布局（standard layout），最常见的一种布局。

1
$PAGE->set_pagelayout('standard');

在设置页面布局时，你应该使用最接近你当前要创建的页面的布局。布局被主题（theme）调用，主题决定要展示的样式。布局之间最大的区别就在于他们对板块（block）区域的支持。默认的布局base不支持板块区域，standard布局是最常见的布局，支持一些板块区域。

Moodle有许多种布局，Moodle中大量的使用了它们，你也可以在你自己的代码中使用。你可以在theme/base/config.php文件中查看所有的布局，下面的列表中也列出了所有的布局。

注意: 主题决定了布局的样式，以及哪种布局是可用的。如果你选择了一个当前主题不支持的布局，那么它会变为当前主题的默认布局。

主题也可以指定新的布局。需要指出的一点是，一个主题自设的布局可能在其他主题下不能正常使用。

Base主题的页面布局

下面是一个Base主题中含有的布局的列表。主题设计器（Theme designer）鼓励第三方的主题继承于Base主题，从而保证在99%的情况下，这些布局都是可用的。

Layout Description
base Most backwards compatible layout without the blocks. This is the layout used by default.
standard Standard layout with blocks, this is recommended for most pages with general information
course The course main page uses this layout.
coursecategory Category course listings.
incourse Used for areas within a course, typical for modules. Default page layout if $cm specified in require_login().
frontpage The site home page uses this.
admin Admin and settings pages as well as server administration scripts.
mydashboard The users dashboard.
mypublic A users public profile uses this layout.
login The login screen.
popup Pages that appear in popup windows, usually no navigation, blocks, or header.
frametop Used for the outermost content of a page constructed with frames. Usually no blocks and minimal footer.
embedded Embedded pages such as content for iframes/objects. Needs as much space as possible usually no blocks, header, or footer.
maintenance Used during upgrade, installation, and when maintenance mode is enabled.
print Gets used when printing a page. Normally just a simple header and no blocks.
redirect A special layout used during a redirect. Normally with content only.
report Used for reports within Moodle. Special layout designed to handle horizontal scrolling in a nice way.

标题（title）

对任何设计好的页面来说，标题都是必不可少的。虽然这是可选的，但是我们还是强烈建议你设置页面的标题。

1
$PAGE->set_title('This is my title');

在设置标题时，你需要提供你希望的标题字符串，这个字符串不应含有html标签，任何html标签都会被过滤掉，Moodle会使用<title>标签来显示标题。

页面首部（heading）

和标题一样，我们强烈推荐你为页面设置一个有意义的页面首部，尽管这是可选项。

页面首部通常会被展示在页面的最上方，这决定于你当前使用的主题。不是所有的主题都会显示页面首部，然而即使你在使用一个不支持页面首部的主题，我们仍然鼓励你设置页面首部。通过下列方式设置的页面首部不会干扰到某些主题设置的对所有页面都相同的页面首部。

1
$PAGE->set_heading(get_string('pluginname', 'local_myplugin'), 3);

页面首部的文字也应该是不带有任何html格式的。（有关这个问题仍存在争议）

后面的部分明天更新

高级设置

获取页面信息

问题及解决方案

相关的API