Gotcha Of The Day: Getting A Joomla 1.5 Plugin To Function

I'm upgrading a client's Joomla from 1.0 to 1.5, and in the process porting over some existing Mambots to 1.5 Plugins.

The OO interface of Joomla 1.5 is definitely a vast improvement over 1.0. Yet, even with the provided tutorial, I couldn't seem to get my Plugin to work. Here's a few of the big hurdles I had to clear before I could get my first plugin working.

For the sake of a comparable example, suppose I wanted create a plugin that replaced all instances of the word and with or. I started off with the following to files in and.zip and installed them (oh, and don't forget to activate the plugin after install!):

and.xml:

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="system">
  <name>And to Or</name>
  <author>Ben Simon</author>
  <authorEmail>questions@ideas2executables.com</authorEmail>
  <authorUrl>http://www.ideas2executables.com/</authorUrl>
  <version>1.0</version>
  <description>Map all instances of And to Or</description>
  <files>
    <filename plugin="and">and.php</filename>
  </files>
</install>

and.php:

<?php
defined( '_JEXEC' ) or die( 'Restricted access' );
jimport( 'joomla.plugin.plugin' );

class AndPlugin extends JPlugin {

  function onPrepareContent( &$row, &$params, $page=0 ) {
    $row->text = preg_replace("/and/i", "or", $row->text);
  }
}
?>

The first issue I ran into was a misconfiguration in and.xml -- I had copied the tutorial's XML file, which had the group set to system. As a result, it was never going to invoke the plugin for content. I fixed this by tweaking the XML to say:

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="content">
  <name>And to Or</name>
  <author>Ben Simon</author>
  <authorEmail>questions@ideas2executables.com</authorEmail>
  <authorUrl>http://www.ideas2executables.com/</authorUrl>
  <version>1.0</version>
  <description>Map all instances of And to Or</description>
  <files>
    <filename plugin="and">and.php</filename>
  </files>
</install>

I uninstalled, and re-installed the plugin - still, no dice.

After poking around the code, and re-reading the tutorial, I realized I had named my file incorrectly. It needs to be named exactly: plg«Section»«Name». I fixed this by changing the code to say:

<?php
defined( '_JEXEC' ) or die( 'Restricted access' );
jimport( 'joomla.plugin.plugin' );

class plgContentAnd extends JPlugin {

  function onPrepareContent( &$row, &$params, $page=0 ) {
    $row->text = preg_replace("/and/i", "or", $row->text);
  }
}
?>

For this change, I was able to just FTP the new source file in place and didn't have to bother with the uninstall/install dance. But still, no luck.

After even more poking around, I realized that the constructor that I thought superfluous, was in fact critical. Without adding the following line of code, the plugin never gets registered with the event system, and the onPrepareContent is never invoked. I fixed this like so:

<?php
defined( '_JEXEC' ) or die( 'Restricted access' );
jimport( 'joomla.plugin.plugin' );

class plgContentAnd extends JPlugin {


  function plgContentAnd($subject, $config) {
    parent::__construct($subject, $config);
  }

  function onPrepareContent( &$row, &$params, $page=0 ) {
    $row->text = preg_replace("/and/i", "or", $row->text);
  }
}
?>

Whew. With all these conventions noted - I'm officially on good terms with Joomla 1.5. Turns out, we're going to be friends after all.