Moodle API文档 —— Form API

概述

Web表单在moodle中的创建方式是使用forms API,它提供了所有的html元素(例如checkbox, radio, textbox等),并且更加安全易用。

Form API的特性

  • 在主流屏幕阅读器(Dragon、JAWS等)上进行过测试和优化
  • 使用tableless layout
  • 通过required_param, optional_param 和 session key等方式对表单中的数据进行了安全性检查
  • 支持多种客户端
  • 可以方便的添加moodle帮助按钮
  • 通过File API提供对文件仓库的支持
  • 提供了自定义的多种表单元素
  • 加入了重复元素的支持
  • 加入了高级表单元素

Form API的使用

为了在moodle中创建一个表单,你必须新建一个继承于moodleform类的类,并且重写它的definition()函数来加入你想要的表单元素。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
//moodleform is defined in formslib.php
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {
//Add elements to form
public function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement('text', 'email', get_string('email')); // Add elements to your form
$mform->setType('email', PARAM_NOTAGS); //Set type of element
$mform->setDefault('email', 'Please enter email'); //Default value
...
}
//Custom validation should be added here
function validation($data, $files) {
return array();
}
}

之后可以在其他地方实例化该表单类。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
//include simplehtml_form.php
require_once('PATH_TO/simplehtml_form.php');

//Instantiate simplehtml_form
$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);
//displays the form
$mform->display();
}

表单元素

基础表单元素

  • button
  • checkbox
  • radio
  • select
  • multi-select
  • password
  • hidden
  • html -div element
  • static -显示一个静态的文本
  • text
  • textarea

自定义的表单元素

  • advcheckbox -高级的复选框
  • passworddunmask -允许以明文方式查看的密码输入框元素
  • recaptcha
  • selectyesno
  • selectwithlink
  • data_selector
  • date_time_selector
  • duration
  • editor
  • filepicker -上传单个文件
  • filemanager -批量上传文件
  • tags
  • addGroup
  • modgrade
  • modvisible
  • choosecoursefile
  • grading
  • questioncategory

上述元素的具体使用方法会在后面的文档中介绍

可能会用到的函数

add_action_buttons();

你通常可以使用这个帮助函数来帮你自动在表单最后添加所有的action按钮。传入的两个参数允许你设置是否需要cancel按钮并设置submit按钮的显示文字(通过get_string()函数获取),默认的显示文字是通过get_string('savechanges')函数来获取到的。注意要使用$this而不是$mform

1
$this->add_action_buttons();

setDefault()

设置元素的默认值

disableif()

对表单中的任何元素或元素组你可以有条件的将其设置为不可见。

addRule()

给客户端/服务器的确认增加一条规则,例如文本必须为email格式

setHelpButton()

为一个表单元素设置弹出样式的帮助框

addHelpButton()

为一个表单元素添加一个弹出样式的帮助狂

setType()

它的参数用来指定提交的数据的类型

disable_form_chage_checker()

默认情况下,在你进行了修改后没有进行保存就尝试离开当前页面的时候,所有的moodle表单会弹出一个”你确定要离开吗?”的对话框。有时候不需要这样的机制,你就可以通过调用$mform->disable_form_change_checker()来取消这一功能。

设置元素组

在之后的文档中会介绍

文章目录
  1. 1. 概述
  2. 2. Form API的特性
  3. 3. Form API的使用
  4. 4. 表单元素
    1. 4.1. 基础表单元素
    2. 4.2. 自定义的表单元素
  5. 5. 可能会用到的函数
    1. 5.1. add_action_buttons();
    2. 5.2. setDefault()
    3. 5.3. disableif()
    4. 5.4. addRule()
    5. 5.5. setHelpButton()
    6. 5.6. addHelpButton()
    7. 5.7. setType()
    8. 5.8. disable_form_chage_checker()
  6. 6. 设置元素组