Filters 1.9 and before

Please note: This page contains information for developers. You may prefer to read the information about filters for teachers and administrators.

---

Filters allow for the for the automatic transformation of entered text into different, often more complex forms. For example the titles of Resources can automatically become hyperlinks that take you to the relevant resource, URLs pointing to mp3 files can become Flash controls embedded in the webpage that let you pause and rewind the audio. The possibilities are endless and there are a number of standard filters included with Moodle and many more specialized filters contributed by the community.

To create a filter

To create a filter that removes all occurrences of the letter "x" - we'll call it "removex":

1. Create a new folder inside Moodle's /filter/ folder, called "removex"
2. Create a new PHP script file inside the folder you've just created - name it "filter_removex.php"
3. Write a new PHP function in this file, called "filter_removex()" which takes two parameters - a piece of text to be filtered and a course ID - and returns the processed text.

For our example the function would look like:

function filter_removex($text, $courseid) {
    return str_replace("x", "", $text);
}

When trying this out, remember to make sure that you activate the filter in the filters administration screen.

Also remember that text filtering functions, when activated, will be used intensively by the server, so you should optimise the filters as far as possible (cut down on database calls etc). Moodle caches the results of filtering to help with processing speed, but it's still worth being careful about your filter design.

Filters are applied to all text that is printed with the output functions format_text() or format_string(). One thing to keep in mind when designing the filter is that the function format_text() first applies other transformations (for example text_to_html() or replace_smilies()) before the strings are passed to your filter. The function format_string() on the other hand passes the string as it is.

Adding a settings screen

Moodle 1.6 added the options for filters to have their own settings screen. To do this perform the following steps:

• In the same folder as the filter create a file called filterconfig.html.
• For the parameters you want to be edited provide appropriate form fields (note you should not provide the actual form tag itself)
• The format of the field names should be filter_filtername_fieldname; where filtername is the name of the filter (ie, the name of the folder) and fieldname the name of the field (filter is the actual word filter). The field will be created as a config variable, so you can display the current value with $CFG->filter_filtername_fieldname. Example:

   <textarea type="text" name="filter_censor_badwords" cols="60" rows="10">
       <?php echo "$CFG->filter_censor_badwords"; ?>
   </textarea>

• you will need to pay attention to setting the default value for these parameters. As filters are pluggable it is best to do it in the filter, but bear in mind that you must check the default both in the settings screen and in the filter itself as you cannot know which will be called first. Some filters with extensive lists of parameters call an external script for this purpose (see, for example, the multimedia filter)

See also

• Filters schema - a page containing some ideas and thoughts about modifications to the filters system
• Filters (administrator)