主页
► Page API
Page API
API页面用于创建当前页面,添加JavaScript和配置如何向用户展示内容。
内容
[隐藏]
·1概述
·2一个简单的例子
·3模板全局页
·4设置页面
·4.1 URL
·4.2内容
·4.3选项设置
·4.3.1页面布局
·4.3.2基本主题页面布局
·4.3.3标题
·4.3.4标题
·4.4高级设置
·5页面详情
·6常见问题
·7相关的API
·7.1 API输出
·7.2 API页面需求
·7.3API导航
·8参见
概述
API页面是任何模板页面不可分割的一部分,。它允许开发人员按照他们的设想进行设置。通过API页面你可以设置如标题、初始航向等,在此用户用以导航以及展现出页你认为应该使用的页面布局。
本文档以一个简单的示例开始，然后相继提供关于如何设置展示页面的完整描述。
示例：
这个示例介绍了如何在一个活动插件内建立一个可供使用的基础页面，而且它以相当简单直观的方式展示出大量工作如何在幕后为您完成的。
// 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开始，假设您已经准备好要使用的课程和课程模块对象。当你调用magic的require-logic部分，它已经为你设置好当前页面的基础。
在上述示例中，require_login给出的课程和课程模块已经为你设置好大部分页面。它向页面提供课程和课程模块对象，设置页面内容以及进行课程页面展示,由此你将得到一个课程模块的标准样式。
必须如下设置:
1。设置页面的URL。必须完成。
2。设定页面标题。基本显示在<标题>栏。
3。设置页面标题。基本设置在页首。
这些都是输出前必须完成的步骤。也就是说，你必须在打印页眉前以及举例说明任何模板形式前设置好页面。
如果您添加一点简单的输出,您会得到一个看上起相对成熟的页面。就是如此简单。
$PAGE 模块全局页
为每个页面请求模块设置一些你可能需要的全局结构。$ DB数据库对象和存储的配置$ CFG，你可能已经意识到了这两项。$PAGE 是本文的重点,它是一个moodle_page实例，用以存储所有的信息，以及被$OUTPUT输出库用来展示页面。
需要注意的是$PAGE and $OUTPUT的区别。$PAGE 用来设置页面，$OUTPUT用来展示页面。$PAGE 包含大量的逻辑与magic运算, $OUTPUT 仅仅用于呈现以及创立HTML。
设置页面
当在模块中创建一个页面时，有一些内容是你必须设置的，它包含许多情况，但不占用所有时间。
URL
有一个必须设置项，如果没有设置，模块将会显示出未设置的错误提示，它可以如下设置：
$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页面进行了 3次设置，并突显了3种不同的设置方法。前两个方法是首选方法,因为处理URL时有100%的准确率。所有添加给Moodle-url对象的内容都可以进行内部转换。
API模块核心将会使用你添加给页面的URL。精确设置很重要，因为它将用于创建页面导航。
内容：
这也是一个必须设置项，尽管多数情况下moodle将会为你神奇地设置好。为了设置页面内容你必须提供文本对象，如下：
// 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));
In Moodle 2.0+, and Moodle 2.1+ the following is the equivalent code:
// 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));
上述两个示例中已经显示出对文本的不同形式的设定，但是你应该只用与你已经创建的页面最适合的文本来调用set_context()。
如果它是一个文本插件，那么它应该用于检查性能。
正如上述所提到的其他应知事项，在某些情况下这会自动为您设置。
如果你的脚本调用了require_login(大多数脚本这样)以及你正在为你的require login提供的所需课程或模块，你就不必调用set_context()。
这是因为require_login帮你处理了它。
如果你的脚本没有调用require_login,或者你没有用所需课程或者模块调用它，你就需要如图手动设置文本。
选项设置：
以下是任选附件，您可以对可能出现在模块核心的页面对象进行设置，并且也许你会想要亲自试用这些对象。
页面布局：
以下代码设置了页面标准布局,是阿森纳最通用的布局。
$PAGE->set_pagelayout('standard');
当在设置页面布局时你应该使用与之最匹配的布局。主题决定页面布局。布局之间最显著的差异是它们支持的块区域。默认布局例如“基底”通常没有任何块区域，然而通常“标准”有最常用的布局和一些块区域。
有几十种不同的布局，通过模块核心来使用，这些模块你能运行你的代码来使用。常见布局的完整列表最好基于主题，基底，个人配置或者参看下列列表。
注:有必要知道主题决定布局。如果你选择一种与主题不符的布局，当使用主题时，它将被还原成默认布局。
主题也可以特指额外的布局。但是重要的是识别他们并且知道当布局和一个主题一起运行时，两者不会如你所期待的和谐运行。
基本主题页面布局
下面是一个基本主题定义的布局列表。主题设计师们把基本主题作为自定义主题的根本以保证在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. |
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. |
标题
任何一个合理设计的页面来说都必须设置一个适当的标题。虽然是可选的，但是强烈建议您设置标题。
$PAGE->set_title('This is my title');
当设置页面标题时，你需要提供所需的标题字符串。它应该是基本字符串而不包含任何HTMT。任何HTMT将在HTMT head的标题栏中去除。
标题
强烈建议你设置一个有意义的页面标题尽管它是可选的。通常标题在页首呈现。但是呈现位置还是取决于由主题定义的布局。不是所有布局都要有标题，但我鼓励你使用即使布局不支持标题。这样的话，你的主题要求在每页都使用标题，不管布局如何，它们都显得较为一致。
$PAGE->set_heading(get_string('pluginname', 'local_myplugin'), 3);
当设置一个标题只有一个参数,那就是用于标题的字符串。它应该是一个基本的，不包含HTML的字符串。
高级设置
以下是一些先进的可选方法，你可以用于进一步的页面设置。在大多数情况下,你永远不会需要使用这些。
设置活动记录
如果你用课程模块调用require_login，,或者你在 $PAGE上手动设置课程模块，
然后你可能也会想 在$PAGE上设置活动模块记录。
这样做的好处就是当你已经获取活动记录的情况下,手动设置活动记录的数量可能会减少查询页面的次数。
$PAGE->set_activity_record($activityrecord)
设置块编辑性能
使用这种方法你可以设置一个额外的性能，用户必须能够编辑前拥有此性能。默认网址：运行manageblock，尽管有时可以使用不同的性能。
$PAGE->set_blocks_editing_capability($strcapability)
设置按钮
这允许你设置HTMT，显示在导航条上通常“turn on editing”所在的位置。
$PAGE->set_button($htmlstring)
设置cacheable
通过此设置，错误页面将会以标题形式发送以此阻止客户端发送缓冲页面。默认为正确值。
$PAGE->set_cacheable(true/false)
身份类别设置
允许你设置一个呈现页面的分类组。调用此将会使$PAGE->course 发送至首页。
$PAGE->set_category_by_id($categoryid)
Cm设置
如以上页面设置,有时你需要手动设置 $PAGE课程模块。你必须设置课程内容如果你调用此文本。
$PAGE->set_cm($coursemodulerecord)
这允许你设置课程所属页面。通常当你调用ｒｅｑｕｉｒｅ－ｌｏｇｉｎ，课程将会自动为你发送至$PAGE 。但是如果你不想要课程登录请求而是出现在$PAGE，你可以调用课程设置来提供此功能。但是如果你这么做，必须使用课程文本。
$PAGE->set_course($courserecord)
文档途径设置
通常这会自动为您创建，然而在某些情况下,您可能想要手动设置。这允许你有对同一文档页的许多个页面而不必是一对一的关系。文档页链接通常在页脚显示。
$PAGE->set_docs_path($strpath)
聚焦控制设置
通过此设置，当客户端页面加载时一个元素ＩＤ将会被转化成相应的ＩＤ。多数情况下，使用此项功能是很糟糕的因为浏览器内焦点自动更改对于受损版本以及那些使用屏幕阅读器的人来说很可怕。
$PAGE->set_focuscontrol($controlid)
标题菜单设置
这允许你设置一些ＨＴＭＴ，将会显示在下页主标题上语言选择框通常所在的位置。
$PAGE->set_headingmenu($htmlstring)
其它编辑功能设置
用户必须拥有此项额外的功能才能打开编辑页面。
如果你更多的进行页面编辑更不仅是块编辑，这是非常有用的。
$PAGE->set_other_editing_capability($strcapability)
纸张类型设置
这被自动设置为默认的文件路径，如e.g. mod/mymod/index.php 将会被设置成mod-mymod-index.大多数情况下，这很方便但是偶尔也会被覆盖。
$PAGE->set_pagetype($strpagetype)
定期刷新延迟设置
如果设置一个元标记添加到页眉使它定期刷新。这一般不需要，如果你需要自动刷新的聊天页面或新闻提要还是有用的。今天是不推荐使用这个,而是创建一种通过AJAX获得额外内容的方法。
$PAGE->set_periodic_refresh_delay($intdelay)
弹出通知延迟设置
允许或者禁止此页面的弹出通知。例如消息，有时会在屏幕底部弹出。
在某些页面不需要此功能,可以通过调用这个方法把错误信息作为第一个参数来禁止它。
默认情况下允许弹出窗口。
$PAGE->set_popup_notification_allowed(true/false)
子页设置
如果文本ＩＤ和纸张类型不足以唯一地标识该页面,你需要包含另一个字符串使之更独特。你可以通过调用此方法来设置一个自定义的子页面类型。
$PAGE->set_subpage($strsubpage)
添加ｂｏｄｙ分类
给用ＡＰＩ输出打印的ｂｏｄｙ标签添加一个ＣＳＳ分类将被作为页眉的一部分。给Ｂｏｄｙ标签添加的分类有利于描述页面内容，或可能被要求来定义整体页面，或者包括有利于寻找ＪａｖａＳｃｒｉｐｔ的指标类。
$PAGE->add_body_class($strcssclass)
添加ｂｏｄｙ分来
将一个CSS类数组添加到ｂｏｄｙ标签。
详情请见add_body_class
$PAGE->add_body_classes($arrayofclasses)
页面信息获取
你当然可以从已经设置好的页面中获取信息。任何你在页面设置好的信息都能通过其他方法被检索。以下是你能从页面获得最有趣的和可能有用的东西。
活动记录
活动记录将会记录在数据库，数据库与由命令登录设定的ＣＭ或者手工代码相关联。
例如，如果你提供了一个与$cm 实例相关的论坛,这将成为论坛码的一行。
$var = $PAGE->activityrecord;
块管理
块管理负责加载所有页面上的块。
详情请见API。
$var = $PAGE->blockmanager;
bodyid
这一身份信息将在呈现页面时被添加到主体中。
$var = $PAGE->bodyid
类别
一个数组包含所有页面课程所属类别，以所含类别开始。
$var = $PAGE->categories
类别
页面课程所属类别
$var = $PAGE->category
cm
为页面设置的课程模块。
$var = $PAGE->cm
课程
为页面设置的课程。
$var = $PAGE->course
devicetypeinuse
用户用于浏览页面的设备。
$var = $PAGE->devicetypeinuse
打印的标题
页眉已打印。
$var = $PAGE->headerprinted
标题
页面标题。
$var = $PAGE->heading
导航栏
您可以在引用的页面导航栏进行交互。详情请见API。
$var = $PAGE->navbar
导航
引用页面导航。详情请见API。
$var = $PAGE->
命令
引用页面命令管理处理任何ＪａｖａＳｃｒｉｐｔ和特殊ＣＳＳ页面要求。
$var = $PAGE->requires
导航设置
设置导航的页面。详情请见API。
$var = $PAGE->settingsnav
主题
用于获取页面主题。是一个主题配置对象。
$var = $PAGE->theme
标题
页面的标题。
$var = $PAGE->title
url
被设置为页面的URL。是一个moodle_url对象。
$var = $PAGE->url
常见问题
在我的页面未出现任何讯息块?
这是因为没有使用讯息块设置页面布局，或者是在输出开始之后你才开始设置。一旦输出开始，你不能更改用于原始输出的页面组成部分。这些包包括页面标题,标题、url和布局等。
我已经设置过了但我得到URL页面的未设置提示？
如上，你必须在输出开始前设置好页面，试图这样做将会得到时序错乱警告。
输出何时开始？
当脚本调用echo $OUTPUT->header或者实例化一个模块格式时，输出开始。
关于API
你也应该了解一些与API页面紧密相关的API事项。
API输出
API输出与API页面即刻相关。API页面是关于如何设定，而API输出是关于如何呈现。通过API输出产生内容，你设置的大量页面信息用以定制生产内容以及填满一般空白页（比如标题栏）
详情请见Output API
API页面需求
API页面需求允许开发人员包含额外的CSS和页面所需的JavaScript资源，以及JavaScript通过各种手段来调用页面。技术上讲，这个API是上述输出API的一部分,但是需要特别提出的是，如果你要在你的页面中使用任何JavaScript和CSS,你需要知道这个。
详情请见 Output API
API导航
ＡＰＩ导航与ＡＰＩ页面和输出一样不可或缺。它用于识别显示的文本内容，确保从文本中加载正确的块和导航结构。你必须意识到，很可能在插件页面发展中你会产生一个早期导航定制的需求。
详情请见 Navigation API
另请参阅
·API核心:一份有关模块中所有核心API事项的列表。
·API输出:输出API。
·API导航:导航API。
·开发人员论坛: 供以对API页面的提问。
·mdl - 30977:用以查看对API页面的正确纪录。