Content plugins: Quick examples

Writing a Joomla plugin is a fairly straight forward process. In particular, after reading this article at the Joomla developer community I tried creating a few quick plugin examples of type "content" just to verify their operation. The plugin templates provided in the article are very simple and the whole process is really easy to follow. The motivation behind the attempt was to create smart article headers and footers as well as to embed custom tags in my articles that would be replaced upon display.

Joomla plugins cover various areas like user authentication, content display, content editors, web services and others. For a quick introduction on the various plugin types you can also read this article.

The high level picture behind plugins is this: Joomla incorporates a global dispatcher object that triggers events. Plugins are basically listeners that attach to these events. From our point of view, we just need to declare a class that inherits from the JPlugin class and define methods that will be executed upon event triggering automatically. The good news is the implementation of the dispatcher and the whole event triggering mechanism is (thanks Joomla) hidden to us... It boils down to defining a method, synonym to the triggering event.

The events associated with content plugins are the following:

• onPrepareContent – before any output occurs
• onAfterDisplayTitle – just after the article title is displayed
• onBeforeDisplayContent – just before the content is output, returns the output to be displayed
• onAfterDisplayContent - just after the content is output, returns the output to be displayed

Just to mention here that there is the old way to do this which is function based and requires the Legacy Mode to be on and the new way to do it which is class based.

Note that in contrast with modules, plugins have to be installed before they can be activated thus, get to your Joomla temporary folder (joomla-dir/tmp) and create two files in there, test.xml and test.php. Just in case you haven’t read the module development tutorial or you are very new to this, test.xml defines all the plugin attributes and test.php is the actual code for our "Test" plugin; the name does not look that intuitive I suppose. Anyway, put the following in there.

test.xml

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="content">
        <name>Test</name>
        <description>Test</description>
        <files>
                <filename plugin="test">test.php</filename>
        </files>
        <params/>
</install>

Well, not much for now, we just declare the name of the plugin, its type and the name of the php file with the code in it.

test.php

<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
 
// Import library dependencies
jimport('joomla.event.plugin');
 
class plgcontentTest extends JPlugin
{
    function plgcontentTest (&$subject)
    {
        parent::__construct ($subject);
    }
    function onPrepareContent (&$article, &$params, $page=0)
    {
        print "I am a happy plugin";
    }
}
?>

Now, install the plugin and enable it with the plugin manager.

Navigate to your Joomla installation path. Under the plugin directory you will find subdirectories corresponding to the various plugin types. As you imagined our installed plugin resides under the content directory.

The code template above is the minimum you can have and you may experiment with it without having to reinstall the plugin for every alteration, just do any changes to the joomla-dir/plugin/content/test.php file and press your browser’s refresh button to see the result.

The code template is easy to follow, after restricting access and importing the required library, we just define a class after the type and name of our plugin that extends JPlugin. Please note that the naming convention has to be followed for the event listener method to be invoked automatically. The synonym function is the class constructor that just invokes the parent one; no need to know more on this.

Try this example as well:

function onPrepareContent (&$article, &$params, $page=0)
{
    $article->text = str_replace("a", "b", $article->text);
}

You see how easy it is to parse the article and make substitutions on the fly.

Also, try the following code to have a look at the article parameters:

function onPrepareContent (&$article, &$params, $page=0)
{
    print $params->_raw;
}

Just to ask here, if anyone appreciates what the page thing is, let me know.

Now, as you imagine the possibilities for embedding stuff automatically into your articles are limitless. To give you an example, you can create links on the fly; try substituting all instances of the text 'Joomla' with a link to www.joomla.org. Give it a go.

Or, to get to a more elegant and widely used solution, we can create custom tags. Every kind of code or text can replace tags, say google ads, social bookmarking icons, paypal stuff, youtube videos, flickr images, really whatever. Let's have a look at the rest available events and explore new possibilities.

Add the following code without deleting the onPrepareContent function:

function onAfterDisplayTitle (&$article, &$params, $page=0)
{
    return "We thank $article->author for this great article!";
}

Note here, the text that will be displayed after the title; is being returned and not just printed out. Accessing the article object to use its attributes is common practice.

Similarly, you can add:

function onAfterDisplayContent (&$article, &$params, $page=0)
{
    global $mainframe;
 
    $sitename = $mainframe->getCfg( 'sitename' );
 
    return "This article has been viewed $article->hits times on 
$sitename";
}

Here, we are accessing the mainframe object of the JApplication class that contains many application attributes. The onBeforeDisplayContent event is similar to the above, no need for another example.

Now, to complete the picture and help you appreciate the potential of plugins, I should give you examples on how to use backend parameters, show you how to query the database and then I should dive into regular expressions. Too many things for a quick article, read the first few pages of the Module Development Tutorial, they are of good help.

If there is public demand or the Queen gives me a call, I might expand this.