Moodle插件之Filters（过滤器）
Moodle插件之Filters（过滤器）
过滤器是一种在输出之前自动转换内容的方法。
目的： 创建名为helloworld的过滤器，实现将预输出的“world”字符串替换成“hello world”，并在此基础上升级，提供替换字符串和新字符串的设置，要求过滤器根据设置进行替换。
基本目录结构：
以过滤器名（helloworld）为文件夹，在/filter目录下，即该插件目录为/filter/helloworld；而过滤器插件所有文件/目录均在其中，即/filter/helloworld/*。
以下文件/目录叙述均在插件目录下，即/filter/helloworld/目录下。
步骤：
1. 创建一个基本过滤器
1) 创建一个文件，叫做“filter.php”。
2) 在该文件中，定义一个类称为filter_helloworld，继承moodle_text_filter类。
<?php
class filter_helloworld extends moodle_text_filter {
// ...
}
?>
注：插件类均为插件类别（filter）+插件名（helloworld），用“_”连接。由于是对文本进行过滤，所有继承的是文本过滤的类（moodle_text_filter）。
3) 在这个类中，必须定义一个“filter”方法。该方法需要HTML作为参数被过滤。然后，该方法将转换，并返回处理后的文本。替换“//…”，像这样：
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
return str_replace('world', 'hello world!', $text);
}
}
注：如果该过滤器启用，Moodle输出内容前，会实例化过滤器类，并调用filter方法，对输出内容进行过滤处理。
2. 给过滤器起名
4) 创建一个文件夹名为“lang”，并创建一个子文件夹名为“en”（表示英文），中文为“zh_cn”。
5) 在en目录下，创建一个文件名为“filter_helloworld.php”文件，也就是文件filter/helloworld/lang/en/filter_helloworld.php。
6) 在该文件中，添加
<?php // $Id$
// Language string for filter/helloworld.
$string['filtername'] = 'Hello world!';
只是在语言文件中添加插件名称。
3. 安装过滤器
在安装前，需要定义插件的版本等信息
7) 创建version.php文件
8) 在该文件中，添加如下内容：
//防止通过路径地址直接访问。
defined('MOODLE_INTERNAL') || die();
//插件版本号等信息
$plugin->version = 2016030201;
$plugin->requires = 2016020201; // Requires this Moodle version.
$plugin->component= 'filter_helloworld';
9) 插件安装
管理员登录后，会自动检查插件更新情况，或打开通知页。
我们可以从上图看到version.php中相关内容。然后点击“现在升级Moodle数据库”按钮，即开始安装。
提示安装成功。点击“继续”按钮，进入过滤器管理页面。
4. 测试过滤器
以课程描述为例，若包含字符串“world”，则会被替换成“hello world”。
在启用过滤器之前，如下图：
启用过滤器：
启用之后，输出内容，见下图：
我们可以对比前后输出的课程描述内容，非常明显地说明我们的过滤器有效，当然也可以尝试替换成其他字符串。
- 添加一个全局设置页
添加全局设置，根据设置，对要替换什么，和替换成什么进行操作。
8) 创建“settings.php”文件（Moodle2.6以前是filesettings.php）。
9) 在“settings.php“文件中，添加如下内容：
$settings->add(new admin_setting_configtext('filter_helloworld/word',
get_string('word', 'filter_helloworld'),
get_string('word_desc', 'filter_helloworld'), 'world', PARAM_NOTAGS));
$settings->add(new admin_setting_configtext('filter_helloworld/newword',
get_string('newword', 'filter_helloworld'),
get_string('newword_desc', 'filter_helloworld'), 'newworld', PARAM_NOTAGS));
10) 在语言文件‘filter/helloworld/lang/en/filter_helloworld.php’中添加必要的字符串：
$string['word'] = 'The thing to be replaced';
$string['word_desc'] = 'The hello world filter will replace this word by any other content!';
$string['newword'] = 'The thing to replace old word';
$string['newword_desc'] = 'The hello world filter will replace old word with new word!';
11) 更改过滤器，使用新设置：
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
global $CFG;
return str_replace($CFG->filter_helloworld/word,
$CFG->filter_helloworld/newword, $text);
}
}
$CFG->filter_helloworld/word，可用get_config('filter_helloworld', 'word')来代替，表示获取helloworld插件的word全局设置。
12) 添加设置后，在管理过滤器页直接刷新，即可看到插件的设置按钮，见下图：
点击“设置”，进入设置页面，见下图：
我们可以看到预定的提示信息，以及默认值等，保持默认并保存。
同样地对比红色框中内容，即课程描述，说明过滤器全局设置已经启用，并正常使用。
- 关于性能的说明
当创建一个过滤器并启用后，过滤器将被format_text()或format_string()调用去转换文本输出的每个字节，会造成一定的负载。Glossary（词汇）过滤器是一个例子，在降低负载方面。
如果你的过滤器采用特殊的语法，或是基于对文本的字符串出现，建议在执行完整的正则表达式替换之前，先进行快速和廉价的strpos()搜索。
/**
* Example of a filter that uses <a> links in some way.
*/
public function filter($text, array $options = array()) {
if (!is_string($text) or empty($text)) {
// Non-string data can not be filtered anyway.
return $text;
}
if (stripos($text, '</a>') === false) {
// Performance shortcut - if there is no </a> tag, nothing can match.
return $text;
}
// Here we can perform some more complex operations with the <a>
// links in the text.
}
实际代码参考如下：
public function filter($text, array $options = array()) {
//验证文本是否为字符串，是否为空
if (!is_string($text) or empty($text)) {
// Non-string data can not be filtered anyway.
return $text;
}
global $CFG;
//获取全局配置字符串
$word = get_config('filter_helloworld', 'word');
$newword = get_config('filter_helloworld', 'newword');
//是否包过滤字符串
if (stripos($text, $word) === false) {
// Performance shortcut - if there is no </a> tag, nothing can match.
return $text;
}
return str_replace($word, $newword, $text);
}
到此，简单的过滤器开发基本完成。具体功能结合实际进行添加和调整。
可参考Censor(敏感词)过滤器。
以下为一些关于Censor（敏感词）过滤器说明：
- 文件结构
与上述示例基本相同，包括：
/lang ：所有语言包目录
/lang/en ：英语语言包
/lang/en/filter_censor.php ：英语字符串（翻译）文件
/README.txt ：介绍插件安装、使用等信息。建议添加（尤其是对要发布的插件）。
/filter.php ： 过滤器核心文件，包含过滤器类，及自定义的过滤方法（Moodle会调用）
/settings.php ： 插件全局设置（表单）文件
/version.php ： 包含插件的版本号等信息
- 代码梳理
1) filter.php
2) settings.php
3) /lang/en/filter_censor.php
- 操作展示
1） 管理员登录，并进入网站管理(Site administration)>插件(Plugins)>过滤器(Filters)>管理过滤器(Manage filters)，并找到敏感词(Censor)过滤器，即Word censorship。分别见图中红色和绿色框。
此时该过滤器还没有打开，呈现为灰色字体，且不允许设置和卸载。
列表解释：
Filter（过滤器） ：显示各个过滤器名
Active（是否激活？） ：既是插件状态，也是激活安装。
Order（顺序） ： 既是显示，也是Moodle调用顺序
Apply to （申请） ： 即申请过滤的部分，有内容和标题。
Settings （设置） : 对应的过滤器设置按钮
Uninstall（卸载） : 对应的过滤器卸载按钮
2） 打开该过滤器
选择过滤器的状态为“On”，点击即可激活该过滤器。如下图所示，设置和卸载按钮可用。
3） 设置
点击敏感词设置按钮，进入设置页面（如下图），红色框中内容就是在settings.php中定义的表单元素，以及显示名、描述、默认值等。
输入的过滤字符串，以英文逗号”,”来分割每个词，如“fuck,fucker”。
然后保存即可。
4） 测试过滤器
a) 不启用该过滤器时，测试课程描述是这样显示的：
b) 启用该过滤器，但保持默认（在/lang/en/filter_censor.php中定义），测试课程描述是这样显示的：
c) 自定义过滤内容：“censor”,即表示只过滤字符串”censor“。
保存。
提示成功。
此时，测试课程的描述是这样显示的，可以清晰看出不同操作对应不同的显示内容。
至此，关于敏感词过滤器的相关介绍已经完成。相信你已经了解了什么过滤器，及其使用方法。
