Filters

A Jojo filter is a way of tweaking a particular variable from your plugin. Filters are usually used for tweaking some HTML before it gets displayed on the screen - for example you might use a filter to replace "<br>" with "<br />" so that any user-entered line breaks will be XHTML compliant.

Filters require changes to 2 files, and an understanding of the data you are trying to manipulate.

A filter is a simple function which manipulates a variable. It has a single argument, and outputs the modified variable.

What data do you need to manipulate?

In the Jojo core files, there are many references to Jojo::applyFilter - these are where the filters are applied to specific variables. The most useful ones are listed below in the examples, but filters can be applied anywhere by editing the Jojo core. If you do need to add a filter somewhere in the core, we suggest you do so, then send us a copy of the modified file with an explanation of what was changed and why - where possible we will include your change in the core code so that you will be running on a standard Jojo core, and others can benefit from the new filter point.

For the most part however, we hope the existing filter points will suit the most common tweaks.

your_plugin.php

A filter function needs to be added inside your plugin class. It needs to accept the current data as a single argument, and return the modified value. The following simplified example will convert the BR tags as above.
class JOJO_Plugin_YOUR_PLUGIN extends JOJO_Plugin {
function fixBR($data) {
$data = str_replace('<br>','<br />',$data);
return $data;
}
}

The function can be named anything, and it only needs to be unique within your own class, but do choose something logical. A name of "fixBR" seems appropriate for this example.

api.php

api.php is your way of connecting the filter point to your filter function. It tells Jojo to run your code at the specified filter point. Without this code, your function will not run.
api.php must reside in the main folder of your plugin, that is mysite/plugins/YOUR_PLUGIN/api.php
Jojo::addFilter('content', 'fixBR', 'YOUR_PLUGIN');

There are 3 required arguments here, and one optional.
  • The tag of the filter point you are wanting to modify - in this case "content" refers to the body content of a page.
  • The name of your function you have created - in this case "fixBR". Do keep the capitalisation you use consistent.
  • The name of your plugin - this must be the name of the .php file you have placed the function in, without the '.php' on the end.
  • Optional - The priority of the filter. This is a number from 1 to 10, with 1 being the highest priority (10 is the default).

Priority

As at October 2007, the priority functionality is not implemented, but we have included it in the API for when we do.
Priority indicates the order in which the filters are applied (if there are several competing), with the highest priority filters running first.
The following example will ensure that this filter runs before any others.
Jojo::addFilter('content', 'fixBR', 'YOUR_PLUGIN',1);

Existing tags / filter points

You can apply filters to the following tags, or create your own filter points...
  • content - the main body content on the page
  • title - the H1 heading
  • seotitle - the title of a page, which appears in the browser bar and search engine results (not the same as above)
  • metakeywords - the meta keywords for a page
  • jojo_sitemap - Add your links to the sitemap. Note this is not a string, but an object. (requires the jojo_sitemap plugin installed)
  • jojo_xml_sitemap - Add your links to the XML sitemap. Note this is not a string, but an object. (requires the jojo_sitemap plugin installed)
  • jojo_search
  • rssicon - NOTE - we have plans to rename this to "feedicon" ion the near future.

Examples

Filters are infintely useful, and will be even more useful once more filter points have been added around the Jojo core code. Use regular expressions to replace the content you need, and we suggest Regex Buddy (aff) for this which simplifies regexes if you aren't familiar with how they work.

Custom tags

We are constantly adding custom tags to Jojo for specific projects. Consider the following custom tag, used in a BBCode or HTML editor...
product: green widget
This tag can be replaced by real content using a plugin. It would make sense to replace this with a 'buy now' button or an informational box.
class JOJO_Plugin_YOUR_PLUGIN extends JOJO_Plugin {
preg_match_all('/product:s?([0-9a-z-_s]+)/i', $data, $matches);
foreach($matches[1] as $id => $v) {
if ($matches[1][$id] == 'green widget') {
$replacement = '<a href="products/green-widget/">Buy now!</a>';
} else {
$replacement = '';
}
$data = str_replace($matches[0][$id], $replacement, $data);
}
return $data;
}


More examples to follow.