Moodle filters modify content from the database as it is output to the screen, thus adding function to the display. An example of this is the multimedia filter, which can detect references to video and audio files, and can replace them with a “mini-player” embedded in the content.
How a filter works
Before trying to build a filter, it would help to understand how it works. To begin with, any text written to the screen in Moodle should be processed through the format_text function. The purpose of this function is to process the text, such that it is always safe to be displayed. This means making sure there are no security issues and that any HTML used contains only allowed tags.
Additionally, the output is run through the filter_text function, and this is the function we are interested in. This function takes the text destined for the screen, and applies all enabled filters to it. The resulting text will be the result of all of these filters.
filter_text applies each enabled filter to the text in the order defined in the filter configuration screen (shown in the following screenshot). The order is important; each filter will be fed the output of the previous filter’s text. So it is always possible that one filter may change the text in a way that impacts the next filter.
Building a filter
Now it’s time to build our own filter. To begin with, let’s come up with a requirement.
Let’s assume that our organization, called “Learning is Fun”, has a main website at http://2fun2learn.org. Now, we need any instance of the phrase learning is fun to be hyperlinked to the website URL every time it appears on the screen, as in the forum post shown in the following screenshots:
We can do this by implementing a policy with our content creators that forces them to create hyperlink tags around the phrase every time they write it. However, this will be difficult to enforce and will be fraught with errors. Instead, wouldn’t it be easier if the system itself could recognize the phrase and create the hyperlink for us?
That’s what our filter will do.
Getting started
We need a name for our filter. It is the name that will be used for the directory the filter will reside in. We want a name that will describe what our filter does and will be unlikely to conflict with any other filter name. Let’s call it “learningisfunlink“.
To start with, create a new subdirectory in the /filter directory and call it learningisfunlink. Next, create a new file called filter.php. This is the only file required for a filter.
Open the new filter.php file in your development environment. The filter only requires one function, which is named after the filter name and suffixed with _filter. Add the PHP open and close tags (<?php and ?>), and an empty function called learningisfunlink_filter that takes two arguments: a course ID and the text to filter. When completed, you should have a file that looks like this:
<?php
function learningisfunlink_filter($courseid, $text) {
return $text;
}
?>
We now have the bare minimum required for the filter to be recognized by the system. It doesn’t do what we want yet, but it will be present.
Creating the language file
Log in to the site (that makes use of your new filter) as an administrator. On the main page of your site, look for the Modules Filters| folder in the Site Administration block. Click on the Manage filters link. If you have the default filter setup, you will see your new filter near the bottom of the list, called Learningisfunlink, as shown in the following screenshot:
Now, even though the name is reasonably descriptive, it will be better if it were a phrase similar to the others in the list; something like Main website link.
To do this, we need to create a new directory in our /filter/learningisfunlink directory called lang/en_utf8/ (the en_utf8 is the language specific part—English in this case). In this directory, we create a new file called filter_learningisfunlink.php. This name is the concatenation of the phrase filter_ and the name of our filter.
In this file, we need to add the following line:
$string['filtername'] = "Main website link";
This language string defines the text that will be displayed as the name of our filter, replacing the phrase Learningisfunlink that we saw earlier with Main website link. This file will contain any other strings that we may output to the screen, specifically for this filter.
Once we have created this file, returning to the Manage filters page should now show our filter with the name that we provided for it in our language file.
Creating the filter code
We now have a filter that is recognized by the system and that displays the name we want it to. However, we haven’t made it do anything. Let’s create the code to add some functionality.
Remember, what we want this filter to do is to search the text and add a hyperlink pointing to our website for all occurrences of the phrase “learning is fun”. We could simply perform a search and replace function on the text and return it, and that would be perfectly valid. However, for the sake of learning more about the Moodle API, we’ll use some functions that are set up specifically for filters. To that end, we’ll look at two code constructs: the filterobject class and the filter_phrases function, both of which are contained in the /lib/filterlib.php file.
The filterobject class defines an object that contains all of the information required by the filter_phrases function to change the text to the way the filter wants it to be. It contains the phrase to be filtered, the tag to start the replacement with, the tag to end the replacement with, whether to match case, whether a full match is required, and any replacement text for the match.
An array of filterobjects is sent to the filter_phrases function, along with the text to search in. It’s intended to be used when you have a number of phrases and replacements to apply at one time, but we’ll use it anyway.
Let’s initialize our filter strings:
$searchphrase = "learning is fun";
$starttag = "<a href="http://2fun2learn.org">";
$endtag = "</a>";
Now, let’s create our filterobject:
$filterobjects = array();
$filterobjects[] = new filterobject($searchphrase, $starttag, $endtag);
Lastly, let’s pass the structure to the filter_phrases function, along with the text to be filtered:
$text = filter_phrases($text, $filterobjects);
Our function now has the code to change any occurrence of the phrase “learning is fun” to a hyperlinked phrase. Let’s go test it
