Moodle开发笔记7-Activity module开发

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