Writing a Joomla 1.5 Content Plugin

Posted by: gbluma

Tagged in: Programming , Plugins , PHP , Joomla

This article will show you how to build a quick plugin to replace some text in an article before it get's displayed to the user.

Intro

Lately I've been writing a number of content plugins for Joomla. They're pretty simple, but basically it allows you to transform the content at a number of points in Joomla's process of editing, saving, and displaying of that content. In theory you could use it to do anything but it's common to replace text and/or add special content into the articles.

I used to frown on these types of plugins because it's better to just get the data right in the first place. But sometimes controlling the input just isn't possible or perhaps you need to keep the article in a certain format but display it in another format.

 

Getting Started

What we're going to make is content plugin for Joomla 1.5. The files are laid out as follows:

joomla_path/plugins/content/calculator.php
joomla_path/plugins/content/calculator.xml

Let's just look at the code and I'll break it down some as we go on.

calculator.php:

// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

$mainframe->registerEvent( 'onPrepareContent', 'plgContentCalculator' );


function plgContentCalculator( &$row, &$params, $page=0 )
{
// Get Plugin info
$plugin            =& JPluginHelper::getPlugin('content', 'calculator');
$pluginParams    = new JParameter( $plugin->params );

if (!$pluginParams->get('enabled', 1)) {
$print = true;
}

// find all instances of plugin and put in $matches
$regex = '/{calc\s*.*?}/i';
$matches = array();
preg_match_all( $regex, $row->text, $matches );

foreach($matches[0] as $match) {
$str = str_replace( 'calc', '', $match );
$str = str_replace( '{', '', $str );
$str = str_replace( '}', '', $str );
$str = trim( $str );

$values = explode(' ', $str);

$href="javascript:calculator('" . $values[0] . "', '" . $values[1] . "');";               

if ($print) {
$row->text = preg_replace( '{'. $match .'}', $href, $row->text );
}

}

return true;
}

calculator.xml:

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="content">
	<name>Content - Calculator</name>
	<author>Joomla! Project</author>
	<creationDate>February 2009</creationDate>
	<copyright>Copyright (C) 2008-2009 Lab Eleven. All rights reserved.</copyright>
	<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
	<authorEmail>webmaster@lab11.com</authorEmail>
	<authorUrl>www.lab11.com</authorUrl>
	<version>1.5</version>
	<description>USUCCU Calculator</description>
	<files>
		<filename plugin="calculator">calculator.php</filename>
	</files>
	<params>

	</params>
</install>

Breaking it down

$mainframe->registerEvent( 'onPrepareContent', 'plgContentCalculator' );

We're going to hook our plugin onto Joomla's onPrepareContent event. This happens before Joomla displays the content to the user. Any changes we make to the text will not be saved in the database. (Make sure the second parameter is the name of the function we define next.)

 

 function plgContentCalculator( &$row, &$params, $page=0 )

Here we define  the function that we want  to use for transforming the content.

  • $row is the record from the database  including the content text, author, last-edited.
  • $params is the module parameters returned from joomla.
  • $page has to do with pagination, but we won't use it here
 // Get Plugin info
$plugin            =& JPluginHelper::getPlugin('content', 'calculator');
$pluginParams    = new JParameter( $plugin->params );

These two lines grab objects from Joomla with information regarding our plugin, like whether it's enabled or not.

 if (!$pluginParams->get('enabled', 1)) {
$print = true;
}

These lines will disable output if the plugin is not enabled.

$regex = '/{calc\s*.*?}/i';

$regex is a regular-expression used to find all occurances of {calc xyz} (It looks messed up, but it works)

 // find all instances of plugin and put in $matches
$matches = array();
preg_match_all( $regex, $row->text, $matches );

foreach($matches[0] as $match) {
$str = str_replace( 'calc', '', $match );
$str = str_replace( '{', '', $str );
$str = str_replace( '}', '', $str );
$str = trim( $str );

$values = explode(' ', $str);

... // shortened for clarity (code in next snippet)

}

These lines loop through all the occurrences of  {calc whatever} in the article and break up the second part "whatever" into a list of values. So, {calc 1 2} would have $values = array(1,2);

 $href="javascript:calculator('" . $values[0] . "', '" . $values[1] . "');";                

if ($print) {
$row->text = preg_replace( '{'. $match .'}', $href, $row->text );
}

This builds a string from the values we've parsed out and then replaces the occurances of {calc xyz} in the article text ($row->text).

return true;

Once all of our processing is done we return "true" to tell Joomla everything we've done worked and we've received no errors.