Activity module 是 moodle 里最复杂的 module 类型。 Assignment, Quiz 等 module 都属于 activity module 。
Activity module can support for gradebook connectivity, course groups, course reset, and backup and restore.
一个典型的 Activity 都应该包含下列文件
- mod_form.php - a form to set up or update an instance of this module
- version.php - defines some meta-info
- icon.gif - a 16x16 icon for the module
- db/install.xml - defines the structure of db tables for all database types. Is used during module installation
- db/upgrade.php - defines changes in the structure of db tables. Is used during module upgrade
- db/access.php - defines module capabilities
- index.php - a page to list all instances in a course
- view.php - a page to view a particular instance
- lib.php - any/all functions defined by the module should be in here. If the module name is called widget , then the required functions include:
· widget_install() - will be called during the installation of the module
· widget_add_instance() - code to add a new instance of widget
· widget_update_instance() - code to update an existing instance
· widget_delete_instance() - code to delete an instance
· widget_user_outline() - given an instance, return a summary of a user's contribution
· widget_user_complete() - given an instance, print details of a user's contribution
· widget_get_view_actions() / widget_get_post_actions() - Used by the participation report (course/report/participation/index.php) to classify actions in the logs table.
· Other functions available but not required are:
o widget_delete_course() - code to clean up anything that would be leftover after all instances are deleted
o widget_process_options() - code to pre-process the form data from module settings
o widget_reset_course_form() and widget_delete_userdata() - used to implement Reset course feature.
· To avoid possible conflict, any module functions should be named starting with widget_ and any constants you define should start with WIDGET_
- backuplib.php and restorelib.php (optional)
- settings.php or settingstree.php - (optional) a definition of an admin settings page for this module. mod/assignment/settings.php is a good simple example. mod/quiz/settingstree.php is a more complex example.
- defaults.php - lets you easily define default values for your configuration variables. It is included by upgrade_activity_modules in lib/adminlib.php. It should define an array $defaults. These values are then loaded into the config table. Alternatively, if you set $defaults['_use_config_plugins'] to true, the values are instead loaded into the config_plugins table, which is better practice. See mod/quiz/defaults.php for an example. (This apparently only works with moodle 2.x branch.)
- lang/en_utf8/widget.php - (optional) Lastly, each module will have some language files that contain strings for that module.
Moodle 提供了一个 activity template named NEWMODULE , you can download it at http://moodle.org/mod/data/view.php?d=13&rid=715&filter=1 . 当你开发 activity 时应该 based on NEWMODULE 。需要注意的是, NEWMODULE 还是缺少了非常重要的功能没有涉及: backup and restore 。少了这 2 个功能后果会很严重,很多 moodle system 不会安装缺少这 2 个 function 的 activity module 。
下面以开发一个最为简单的 “Foo” activity 为例。 It includes following features
l gradebook connectivity
l course groups
l course reset
l backup and restore
Step 1 use NEWMODULE as template
1. 下载最新的 NEWMODULE
2. rename “newmodule” folder to our module name “foo”
3. search 目录下所有文件的内容,用 ”foo” 替代 ”newmodule”
4. rename lang/en_utf8/ newmodule.php to foo.php
5. copy the whole “foo” folder to <moodle home>/mod folder
Step 2 修改 mod_form.php (important)
mod_form.php 提供了当 teacher create a new module instance 时出现的 form interface , teacher 可以在该 form 输入对该 module instance 的 setting 。
mod_form.php 要定义一个 mod_<MODULE NAME>_mod_form class ,该 class 需要 extend moodleform_mod class .
require_once ($CFG->dirroot.'/course/moodleform_mod.php');
class mod_foo_mod_form extends moodleform_mod {
在 mod_foo_mod_form class 里,需要定义“ definition ” function ,并在该 function 里创建 form instance, and then add elements (activity instance name, instruction, date selector and grade option ) to the form instance 。 需要注意的是: added element name 必须和对应的 field name in database 相 match !!
function definition () {
global $COURSE, $CFG;
// Create form instance
$mform =& $this->_form;
// creates the form header
$mform->addElement('header', 'general', get_string('general', 'form'));
// create text input
$mform->addElement('text', 'name', get_string('fooname', 'foo'), array('size'=>'64'));
// input element type is controlled by the value of the setType element
$mform->setType('name', PARAM_TEXT);
// UI rules are defined by setting addRule
$mform->addRule('name', null, 'required', null, 'client');
// set instruction ( html editor input )
$mform->addElement('htmleditor', 'instructions', get_string('instructions', 'foo'));
$mform->setType('instructions', PARAM_RAW);
$mform->addRule('instructions', get_string('required'), 'required', null, 'client');
// create html editor help button
$mform->setHelpButton('instructions', array('questions', 'richtext'), false, 'editorhelpbutton');
//create date available ( date selector )
$mform->addElement('date_time_selector', 'timeavailable', get_string('timeavailable', 'foo'), array('optional'=>true));
$mform->setDefault('timeavailable', 0);
$mform->addElement('date_time_selector', 'timedue', get_string('timedue', 'foo'), array('optional'=>true));
$mform->setDefault('timedue', 0);
// set grade ( scale type input )
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
$mform->disabledIf('scale', 'assessed', 'eq', 0);
// 调用 standard_coursemodule_elements 方法 为 common module 进行设置。
// 比如是否 support group 等
// 该方法同时也会 controls the display of multiple form elements.
$features = array('groups'=>true, 'groupings'=>true,
'groupmembersonly'=>true,'outcomes'=>false, 'gradecat'=>false, 'idnumber'=>false);
$this->standard_coursemodule_elements($features);
//add form buttons (cancel and submit)
$this->add_action_buttons();
}
Step 3 修改 version.php
version.php 用于 manage database upgrades and enforce required versions of Moodle. upgrade.php 会根据 version.php 的版本号来决定是否需要升级 (例如 upgrade related table in db )。该文件里定义了
l 该 module 的 current verison
l Moodle 的 require version
l 以及 cron
$module->version = 2009060103;
$module->requires = 2007101509;
$module->cron = 0;
Step 4 修改 icon.gif
Step 5 修改 install.xml
install.xml 定义了 the database structure for the module 。你可以基于 newmodule tempalte 的 install.xml 来通过 moodle XMLDB editor tool or 自己写代码来定义该 module 的 database structure 。
每个 activity module 必须至少有一个 db table ,而且该 table name 必须和 module name 相同。例如 foo activity 的 table name is foo 。该 table 最起码要包含下列 fields : id , name , intro , and modifiedtime
Foo activity 我们在 foo table 里多定义了一些 fields : course , timeavailable , timedue , and scale 。
另外, foo activity 还多定义了一个 table “ foo_responses ” ,该 table 包含了下列 fields : id , fooid , userid , response , and timemodified 。 该 table 用于 store one record for each user response in each foo activity instance 。
另外,在 install.xml 里,还定义了 database statements that are used to store user log data for a user's interaction with the module 。 newmodule template by default 对这部分是在 log_display table 定义了 view, add, and update action for each module 。你也可以添加更多的 action type for logging 。 Activity module 只是使用 default 的 codes
<STATEMENTS>
<STATEMENT NAME=" insert log_display " TYPE=" insert " TABLE=" log_display " COMMENT="Initial insert of records on table log_display">
<SENTENCES>
<SENTENCE TEXT="(module, action, mtable, field) VALUES ( 'foo', 'view', 'foo', 'name') " />
<SENTENCE TEXT="(module, action, mtable, field) VALUES ('foo', 'add' , 'foo', 'name')" />
<SENTENCE TEXT="(module, action, mtable, field) VALUES ('foo', 'update' , 'foo', 'name')" />
??其实上面这段在 table log_display 里添加 3 个 records 有什么用?
对于 install.xml ,如果该 activity module 已经开始使用,而你又有对 install.xml 进行修改,那么就要同时修改 version.php 。如果你是对 install.xml 的 database structure 进行修改,那么还要配合 upgrade.php 来进行 。
Step 6 修改 db/access.php
access.php controls which capabilities can be assigned for user access. Foo activity 定义了 2 个 capabilities :
l mod/foo:submit course student, teacher and admin are allowed
l mod/foo:viewall student role is not allowed
<?php
//Define access capbilities
$mod_foo_capabilities = array(
'mod/foo:submit ' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_MODULE,
'legacy' => array(
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'admin' => CAP_ALLOW
)
),
'mod/foo:viewall ' => array(
'captype' => 'view',
'contextlevel' => CONTEXT_MODULE,
'legacy' => array(
'student' => CAP_PREVENT,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'admin' => CAP_ALLOW
)
)
);
?>
Step 7 修改 index.php (important)
index.php file 会 lists all of the instances of activity that are present in the course 以及当前 logined user 对所有 activity 的 response 。
//include moodle config file and foo activity lib.php
require_once (dirname (dirname (dirname (__FILE__))). '/config.php' );
require_once (dirname (__FILE__). '/lib.php' );
//get course id from request param
$id = required_param( 'id' , PARAM_INT); // course
// 如果 global var $course 与根据 id 从 db 获取的 course 不匹配,则 error
if (! $course = get_record( 'course' , 'id' , $id )) {
error( 'Course ID is incorrect' );
}
require_course_login( $course );
add_to_log( $course ->id, 'foo' , 'viewall' , "index.php?id= $course ->id " , '' );
$strfoos