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()来取消这一功能。

设置元素组

在之后的文档中会介绍