Block 是以一个长方形区域出现在 moodle site 的 page 的左列或右列。 Block 是最简单、也是最常用的 moodle plugin 。

 

下面讲解如何开发一个 hello world moodle block “helloworld”

1. create “helloworld” folder ( 目录名来自你的 module name) in ”moodle/blocks” folder

 

2. 在 ”helloworld” 目录下创建 block page “block_helloworld.php” ( 命名格式是 [ module-type]_[module-name].php )

 

Block php file 要创建一个同名的 class ，该 class extends “block_base” class 。同时需要有 2 个基本的函数： ”init” and “ get_content”

<?php

class block_helloworld extends block_base {

function init() {

$this->title = get_string('helloworld', 'block_helloworld');

$this->version = 2009050700;

}

function get_content() {

if ($this->content !== NULL) {

return $this->content;

}

$this->content = new stdClass;

$this->content->text = 'Hello World!';

return $this->content;

}

}

?>

 

Init 函数至少要设置 2 个变量： block title and block version 。

 

block title 将会显示在 block 区域的最上端。

block version 注意：你每次 upload 你的 plugin to moodle system ，即将上传的 version 必须大于当前存在于 moodle 的 plugin version 。 version 的格式为： YYYYMMDD## 。最后 2 位是 YYYYMMDD 当天的第 n 个版本。例如 2010062903 ，表示 2010 年 6 月 29 日第 3 个 update version

 

get_content 函数所返回值就会作为 block page 显示的 content 。同时它会存储在 $this->content 变量里。

 

以上 2 步就完成了最简单的 helloworld block 。

如何激活？

用 admin account login ，然后 click “ Notifications ” in “ Site Administration ” block ， moodle 就会即时 check and install new plugin 。

 

安装好之后如何使用？

用 admin account login ，然后在你要添加 helloworld 的 page 里启动 edit mode ，然后 in “Blocks ” pull down list ， select “helloworld” block 即可

 

 

上面的 2 步是必须的，下面的步骤是可选的

 

3. (Optional) Add language file (like java message properties file) 。在 ”helloworld” 目录下创建一个 ”lang ” 目录，然后在 ”lang” 下创建一个 ”en_utf8 ” ，它表示这是一个 language folder for Englist with Unicode encoding 。如果你希望有一个 for US 方言的 englist language pack ，那么就在 ”en_utf8” 目录下创建一个 ” en_us_utf8 ” 目录。 在 Moodle里， child language会继承 parent language的所有 string message 。

 

然后在 ”en_utf8 ” 里 创建一个与 block page 同名的 php file ： “block_helloworld.php” ，然后把所有要用到的 message 都放到该文件里。其格式是把这些 messages 都 存储在 ”$string” 数组变量里 。

 

下面一个 language php file 的例子：

<?PHP

$string[ 'helloworld'] = 'Hello World';

$string['helloworld:view'] = 'View Hello World Block';

$string['blockname'] = 'HelloWorld';

?>

 

回顾一下步骤 2 的 init 函数里用到一个函数

            get_string('helloworld', 'block_helloworld');

该函数 Returns a localized string

 

第一个参数对应的是 language file 里的 message key ，例如上例的第一个参数就是对应 language file 里的 ”helloworld” 的 message 。

 

第二个参数是指定来自哪一个 module 的 language file ，例如上例指定的是 helloworld block 。该参数值实际就是存储该 message 的 php file name ( 不要 .php extension) 。例如：我们的 language php file 是 block_helloworld.php ，所以参数值为 ” block_helloworld” 。

 

另外还有一个函数与 get_string 类似，就是 print_string ，它是把返回的 string 输出。

 

4. (Optional but very mportant) Working with capabilities 。 capabilities 见上面的章节。

 

5. (Optional but very mportant) 添加 helloworld block 的 configuration interface ，使得在 edit mode ，在 block 区域里多一个 button link to configuration interface 。

 

例子：使 helloworld block 具有 configuration 功能，使得可以设置 $this->content 的值

1 ）需要在 block main page ” block_helloworld.php ” 的 block_helloworld class里添加一个 return true的 instance_allow_config 函数，代码如下：

function instance_allow_config() {

return true;

}

 

2 ）在 block root 目录下创建一个 config_instance.html file 。该 html file 的代码实际上是 php code ：

<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>

<input type="submit" value="submit" />

<?php use_html_editor(); ?>

 

第一行是输出一个 text area (name 为 text) ，其值为 $this->config->text （ 注意： text area 的 name 的值必须与 $this->context 里的对应的 key name 相同 ），在 submit 之后 text area 的值就会自动赋值给对应的 $this->context 里对应的变量 。例如，该例的 text area 的 name 为 text ， submit 之后该值就会赋给 $this->context->text 。

 

第三行是嵌入 Moodle's integrated WYSIWYG editor 。

 

3 ）修改 block_helloworld class 的 get_content() 函数，使得输出的 content 来自 configuration interface 设置的值。

            $this->content->text = $this->config->text;

 

 

6. (optional) add schedule function to block.

Moodle 的 cron.php 用来运行一个 schedule 来执行 maintenance tasks ，例如 email delivery and backup 。它可能每 5~15 分钟就运行一次。

 

例子：如果 helloworld block 需要执行 schedule task ，你需要

1) 在 block_helloworld class 的 init 函数里添加代码：

                        $this->cron = 5 ;

            这表示每 5秒就会执行下面定义的 cron函数一次。

 

2） 在 block_helloworld class里添加函数 cron()

   function cron() {

print("Hello World is running its cron process./n");

}

 

 

参考书中的另外一个实例： Instructor contact block

 

 

注意：如果我们想在 moodle里添加一个不需要 interface的 module，那么 Block就是最好的选择。对于没有 interface 的 block ， $this->content->text and footer 要设置 empty 。如：

function get_content() {

if($this->content !== NULL) {

return $this->content;

}

$this->content = new stdClass;

$this->content->text = '';

$this->content->footer = '';

return $this->content;

}

 

 

 

官方 moodle block 开发的翻译

Ref link http://docs.moodle.org/en/Development:Blocks

 

以开发一个简单的 ”SimpleHtml” block 为例来讲解。

 

Minimum requirement of block

在 blocks 目录下创建 simplehtml 目录，然后在该目录下创建 block_simplehtml.php

<?php





class

block_simplehtml extends

block_base {

//init method
必须设置var title and version 

function

 init()
{

    $this
->
title
   =
get_string(
'simplehtml'
,
'block_simplehtml'
)
;

    $this
->
version
=
2004111200
;

}

//

function

 get_content()
{

  //check content
是否为null
是因为moodle
的内部机制在一个php page
里可能对同一个block
的instance
都会call
几次，那么为了提高性能，我们只会在创建该block instance
时（这时content=null
）才为其赋值




    if
(
$this
->
content
!==
NULL

)
{

      return
$this
->
content
;

 
 
}

  $this
->
content
         =
  new

stdClass;

  $this
->
content
->
text
   =
'The content of our SimpleHTML block!'
;

  $this
->
content
->
footer
=
'Footer here...'
;

  return
$this
->
content
;




  }

}

?>

 

Enable Configure block

首先在 block_simplehtml class 里添加下面的 function 使得该 block 可以 configure

function

 instance_allow_config()
{

  return
true

;

}

 

然后在 simplehtml 目录下创建一个 config_instance.html 文件，该文件包含当 user 点击 block 的 configuration button 时要显示的 configuration page 的 content

<?php

 print_string(
'configcontent'
,
'block_simplehtml'
)
;
?>

:




<?php

print_textarea(
true

,
10
,
50
,
0
,
0
,
'text'
,
$this
->
config
->
text
)
;
?>





<
input type=
"submit"
value=
"<?php print_string('savechanges') ?>"
/>




<?php

use_html_editor()
;
?>

 

上面的代码就是一个简单的 configuration page 。你会奇怪怎么没看到 <form> ？对的，不需要写 <form> ，只需要提供你需要 config 的东东的 input ，以及一个 submit button 即可。当你 click submit button 时， moodle 会自动波帮你存储 config setting 到 $this->config 里。例如上例 name 为“ text ”的 input field value 就会存储在 $this->config->text 里 。 this->config 变量可以供 block_simplehtml class 里除了 init() method 之外的任何地方调用！

 

下面我们修改 block_simplehtml 的 getContent function 来使用 configuration var this->config

function

 get_content()
{

    if ( $this -> content !== NULL ) {

      return $this -> content ;

    }

 

    $this -> content =   new stdClass;

    $this -> content -> text    = $this->config->text ;

    $this -> content -> footer = 'Footer here...' ;

 

    return $this -> content ;

  }

 

 

Specialists

我想在 configuration page 里设置 block 的 title ，则在 config_instance.html 里添加

<
input type=
"text"
name=
"title"

        value=
"<?php echo $this->config->title; ?>"
/>

 

但由于 $this->config 变量不能在 init() method 里使用以及 $this->title 不能在 getContent function 改变，所以无法在 init() 里或在 getContent method 里使用下列代码

    $this -> title    = $this->config->title;

 

怎么办？就要使用到 specialization() method 来给 title 赋值 ，该 method 是紧接着 init() 后被调用，即是在 before block's content is computed for the first time 之前被调用。

 

同时 specialization() method is the natural choice for any configuration data that needs to be acted upon "as soon as possible" ，即可以对 this->config 包含的值进行预处理 。例如下列代码会在 specialization method 里 check 如果 this->config->text 为 empty ，则给一个 default value 给它。

 

function

 specialization()
{

  if
(
!
empty
(
$this
->
config
->
title
))
{

    $this
->
title
=
$this
->
config
->
title
;

  }
else
{

    $this
->
config
->
title
=
'Some title ...'
;

  }

  if
(
empty
(
$this
->
config
->
text
))
{

    $this
->
config
->
text
=
'Some text ...'
;

  }
    

}

 

Now You See Me, Now You Don't

有时你可能想开发一个这样的 block ：当有数据时，就显示该 block ，但当没有数据时，就隐藏整个 block 。典型的例子是 ”recent activity” block ，如果没有 recent activity ，该 block 就会自动隐藏。

 

怎么实现这个功能？

很简单，只需要在 get_content() 里设置 $this->content->text and $this->content->footer 为 empty string 即可 。（ moodle 在处理 block 时，会先 call is_empty() method 来 check it ，如果 text and footer is empty ，就不会显示这个 block 。

 

注意：不管该 block 的 title 是不是 empty ，也不管 hide_header() method 是 hide or show header ，都不会影响上述 show/hide block 的 behavior 。即当 content is empty 时，即使 title 不为 empty ，也不 hide header ， moodle 照样还是会隐藏该 block 。

 

 

Allow multiple block instance in a course

如果你希望在同一个 course 里添加同一个 block 的多个 instance ，则要在 block class 里添加 instance_allow_multiple method

function instance_allow_multiple() {

  return true ;

}

要注意的是

1． 即使 block 本身 support multiple instance ， admin 还是可以通过 Administration/Configuration/Blocks page 来 disable multiple 功能 。

2． 如果“ allow multiple ”和“ allow config ”同时存在，则会自动 disable allow config function 。

 

 

The Effects of Globalization

有时候 admin 可能希望他能够有一个地方对某个 block 的所有 instance 能一次性进行设置 。

 

例如， admin 希望 simplehtml block 的 content 长度不要超过 200 字，或者 content 只允许 plain text ，如果是 html text ，则 filter html tag

 

首先，在 block class 里添加下列代码

function

 has_config
()
{

  return
true

;

}

 

然后，创建一个 file config_global.html ，该 file is for the configuration screen output . 在该 configuration page ，我们添加一个 checkbox saying "Do not allow HTML in the content" 以及一个 "submit" button.

 

<
input type=
"hidden"
name=
"
block_simplehtml_strict
"
value=
"0"
/>

<
input type=
"checkbox"
name=
"
block_simplehtml_strict
"
value=
"1"

   <?php

if(!empty($CFG->block_simplehtml_strict)
)

             echo
'checked="checked"'
;
?>

/>

 <
p>

 <
input type=
"submit"
value=
"<?php print_string('savechanges'); ?>"
/>

 </
p>

 

上面的代码会 global configure 变量 block_simplehtml_strict ，该变量的值在 submit 时会储存在 $CFG-> block_simplehtml_strict 里 。注意设置的变量名一定要是唯一，如果别的 module 在 $CFG 使用同样的变量名，那就惨啦。所以把变量命名为 block_simplehtml_strict 应该是 ok 的。

 

上面代码你会奇怪为什么有 2 个 input field （一个 hidden [always 0], 一个 checkbox ）的 name 都为 “ block_simplehtml_strict ” ? This is a trick 。因为如果没有 hidden input field ，当 checkbox 没有被勾上，该 variable (block_simplehtml_strict=0) 根本就不会 pass 给 request 。这样就无法设置 $CFG->block_simplehtml_strict=0 。因此加多一个 hidden 是为了保证 request param 里一定有 block_simplehtml_strict variable 。

 

原理就是：当 PHP 处理 form request 时，会按 the variables 在 form 里的出现顺序进行处理。当遇到一个之前已经存在并处理了的 variable ，新值就会覆盖旧值。利用这一点，我们就把 hidden "block_simplehtml_strict" =0 放在前面， checkbox 放在后面。如果没勾上 checkbox ，就会有 hidden 的值 0 ，如果勾上，就会使用 checkbox 的值 1 。

 

如果你觉得用 2 个 input field 来使用同一个 name 太令代码 confuse ，有一个替代方案： overwrite config_save() method （当在 global configuration page click submit button 时，就会调用它） 。

下面代码是缺省的 config_save() method ，其中参数 $data 是 form request variable key value pair array 。

function

 config_save($data)
{

  // Default behaviour: save all variables as $CFG properties

  // You don't need to override this if you 're satisfied with the above

  foreach ($data as $name => $value) {

    set_config($name, $value)
;

  }

  return
TRUE

;

}

 

我们重写它使得它会 check 是否存在 block_simplehtml_strict variable. 如果不存在，就表示没有勾上 checkbox 。使用这个方法就不需要添加 hidden input field 了， I like it .

function

 config_save(
$data
)
{

  if
(
isset($data['block_simplehtml_strict'])
)
{

    set_config('block_simplehtml_strict', '1');

  }
else
{

    set_config('block_simplehtml_strict', '0');

  }

  return
true

;

}

 

OK 。在 global confirmation page 里设置了 $CFG->block_simplehtml_strict ，那在我们的 simplehtml block 里如何使用它？ 其实 $CFG 是一个超全局变量，任何地方都可以使用它 。

 

那么在本例中我们希望根据 $CFG->block_simplehtml_strict 这个 block global configuration ，来使得 block instance 的 content 只能是 plain text ，如果有 html text 就 filter 。这时我们要 overwrite instance_config_save() method ！

instance_config_save()

该方法允许你 override the storage mechanism for your instance configuration data ，即当在某一个 block instance 的 configuration page 里 click submit button 时，就会先调用该方法，你可以重写它来对 submit form data 进行处理，处理完的最后再 call parent::instance_config_save($data) 来调用父类缺省的 instance_config_save method 。 . 该方法的参数是一个 associative array ，它包含有 submit form 的 key/value pair 。 缺省的 instance_config_save 如下：

function instance_config_save( $data ) {

  $data = stripslashes_recursive( $data ) ;

  $this -> config = $data ;

  return set_field( 'block_instance' , 'configdata' , base64_encode ( serialize ( $data )) ,

                      'id' , $this -> instance -> id ) ;

}

从上面缺省的方法可以看到，它会先调用 stripslashes_recursive 方法对 submitted POST data 进行 stripslashes and recursive 的处理，然后才调用 set_field 方法把处理后的 data 存到 db 里该 block instance record 的 "configdata" field 里 。

 

好了，现在我们通过重写 instance_config_save 来 filter html tag

function

 instance_config_save(
$data
)
{

  global
$CFG
;

  if
(
!
empty
(
$CFG
->
block_simplehtml_strict
))
{

    //filter html tag

    $data->text = strip_tags($data->text);

  }

  //

call parent instance_config_save method

  return parent::instance_config_save($data);

}

 

 

hide_header()

如果你想 hide block title/header ，那么添加下列方法到 block class

function

 hide_header()
{

  return
true

;

}

注意： moodle 不允许在 block 的 init() method 里把 title 设置为 empty 。

 

 

preferred_width()

设置 block 的 prefer width 。 Moodle 对 block 的 width 的处理过程包括 2 parts ：首先 moodle 会 query 在 course page 里的每一个 block 的 prefer width ，然后使用最大的 prefer width 作为 desired value 。因此当你设置 prefer width 时， moodle 不一定保证一定以这个 prefer width 来显示，但显示该 block 时应该不会小于该 prefered width 。

 

所有的 standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive. 当你使用下列代码时：

function

 preferred_width()
{

  // The preferred value is in pixels

  return
200
;

}

就会使你的 block width 大于 standard 的

 

 

html_attributes

()

该方法是用来控制处理 block 的 container 的 。每一个 block 都会包含在 <div> or <table> container 里（即 block html code 会包含在 <div> or <table> 里）。那么该方法可以通过添加一些 attributes 来设置包含 block 的 container 。具体方法有下列 2 种

a)      directly affect the end result (if we say, assign bgcolor="black")

b)      给 container 一个 class ，从而利用 CSS 来控制

 

下面的例子就用到第二种方法。

function

 html_attributes()
{

  return
array
(

    'class'
       =>
'sideblock block_'
.
$this->name()

,

    'onmouseover'
=>
"alert('Mouseover on our block!');"

  )
;

}

以上代码把包住 block 的 container 设置为 class=sideblock block_xxx ，这样我们就可以 use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

 

另外把 onmouseover 赋予该 block 的 container ，使得当鼠标进入该 container 时，就 alert.

 

缺省的 html_attributes() method 。

function

 html_attributes()
{

    // Default case: an id with the instance and a class with our name

    return
array
(
'id'
=>
'inst'
.
$this
->
instance
->
id
,

                
'class'
 =>
'block_'
.
$this
->
name
())
;

}

If you intend to override this method, you should return the default attributes as well as those you add yourself . The recommended way to do this is:

function

 html_attributes()
{

    $attrs = parent::html_attributes();

    // Add your own attributes here, e.g.

    // $attrs['width'] = '50%';

    return $attrs;

}

 

applicable_formats

()

该方法是用来控制 block 可以在哪里使用 。有些 block 可能开发者不希望在所有地方都能够使用，例如 "Social Activities" block 只适用于 social format 的 course ，对于 week format 的 course 并不合适，因此 block 需要设置为只有 social format 的 course 才能够添加该 block ，就要用到 applicable_formats method 。

 

注意：在 applicable_formats method 里定义哪些地方可以使用 block ，是以 page 为设置，而不是以 course 来设置。 这是因为 blocks can be displayed in any page that supports them 。例如， the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks

例 1 ：

function

 applicable_formats()
{

  return
array
(

           'course-view'
=>
true

,

    
       
'course-view-social'
 =>
false

)
;

}

上述代码先设置了允许所有的 course 的 view.php page 都可以添加该 block ，然后再 disallow social format 的 course 的 view page 不能够使用它 。

 

例 2 ：

function

 applicable_formats()
{

  return
array
(

           'site-index'
=>
true

,

          'course-view'
=>
true

,

   'course-view-social'
=>
false

,

                  'mod'
=>
true

,

             'mod-quiz'
=>
false

  )
;

}

上述代码设置了 a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, except quiz 。

 

例 3

function

 applicable_formats()
{

  return
array
(
'site'
=>
true

)
;

}

 

上述代码设置了 a block appear only in the site front page ( 如果省略 page name ，则看作是 index page ，即 site = site-index)

 

从上面的例子可以看出 page format name 的格式定义方法 。 例如，

l  如果你需要设置 /course/view.php 是否能够使用 block ，则 format name of that page is course-view .

l  类似的，请理解 a quiz view page is mod-quiz-view

定义 format name 的规则

1. The format name for the front page of Moodle is site-index .
2. The format name for courses is actually not just course-view ; it is course-view-weeks , course-view-topics , etc.
3. Even though there is no such page, the format name all can be used as a catch-all option .

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

1. Prefixes of a format name will match that format name; for example, mod will match all the activity modules. course-view will match any course, regardless of the course format. And finally, site will also match the front page (remember that its full format name is site-index ).
2. The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, mod , mod-quiz and mod-quiz-view all match the quiz view page. But if all three are present, mod-quiz-view will take precedence over the other two because it is a better match.
3. The character * can be used in place of any word. For example, mod and mod-* are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
4. The order that the format names appear does not make any difference.

 

 

cron

要使 block 具有 task schedule 功能，只需要 2 步

Step 1: add function cron

function

 cron
()
{

    mtrace(
"Hey, my cron script is running"
)
;

    // do something

    return
true

;

}

 

Step 2: in init() method, set the (minimum) execution interval for your cron function

        
$this
->
cron
 =
300
;

 //set 5 minutes interval

 

注意：如果你修改了 cron interval ，你必须修改 block 的 version number ，然后 visit  Notifications page 才能生效 。

 

NOTE: The block cron is designed to call the cron script for that block type only . 也就是说 cron 并不关心该 block 有多少个 instance 。 在 cron function 里，你如果需要获取 block instance ，你要自己写代码来 iterate over them 。

例：

function

 cron
()
{

    // get the block type from the name

    $blocktype = get_record( 'block', 'name', 'my_block_name' );

    // get the instances of the block

    $instances = get_records( 'block_instance','blockid',$blocktype->id );

    // iterate over the instances

    foreach
(
$instances
as
$instance
)
{

        // recreate block object

        $block
=
block_instance(
'my_block_name'
,
$instance
)
;

        $someconfigitem
=
$block
->
config
->
item2
;

    }

}

 

Lists and Icons type block

它是一个只提供 item list 的 block type ，该 list 的每一行只显示一个 item and an optional image (icon) next to the item 。典型的例子就是 course page 里的 ”administration” block 。

 

开发这种类型的 block ，你应该 extend block_list ，而不是 block_base 。另外，在 getContent 里不是使用 $this->content->text ，而是使用 $this->content->items and $this->content->icons array 。

class block_my_menu extends block_list {

     // The init() method does not need to change at all

function get_content () {

  if ( $this -> content !== null ) {

    return $this -> content ;

  }

 
  $this -> content          = new stdClass;

  $this -> content->items  = array();

  $this -> content->icons  = array();

  $this -> content -> footer = 'Footer here...' ;

 

  $this - >content->items[] = '<a href=" a .php">Menu Option 1</a>' ;

  $this - >content->icons[] = '<img src="1.gif" />' ;

  // Add more list items here

  return $this -> content ;

}

}