Creating a single install package for a plugin that works on Joomla 1.0, 1.5, 1.6, and beyond

I wanted to create a plugin which runs on ALL versions of Joomla, from 1.0 to 1.6. Rather than maintain and distritube 3 separate install packages, I wanted to create a single install package that would work on all 3 versions of the CMS. This is no mean feat, as each CMS has different expectations when it comes to the installation manifest file (the xml file). After a lot of trial and error, I discovered a way to do it...

For the plugin to work in Joomla 1.0, the xml manifest file needs to go in the root folder - Joomla 1.0 will not look any deeper. Joomla 1.5 and 1.6 will look deeper than the root folder. So as long as we supply something within a folder for Joomla 1.5 and 1.6 to find, the Joomla 1.0 manifest file will be ignored by them.

This makes it fairly easy to cater for the different requirements of Joomla 1.0 in comparison with 1.5 and 1.6. For Joomla 1.0 to be able to use the plugin (mambot) file that's going to be stored in the folder though, an extra file needs to be included in the root folder, named according to the plugin name (eg. my_plugin.php), which simply 'includes' the file in the folder. All 3 CMSs can therefore use the same actual PHP file for the plugin (and you will have to code for the differences as necessary, but at least you only have one code file to maintain). If you're confused at this point, don't worry, it will become clear later.

So that just leaves us with the problem of supplying a manifest file for Joomla 1.5 and another one for 1.6 or a single file for both. As the format of the file has changed in 1.6, it seems as though we cannot use a single file for both. However, they both want a file with the same name (ie. matching the name of the plugin), so we seem to be stuck.

Still, we can make use of a quirk shared by both Joomla 1.5 and 1.6 by using 2 different manifest files: one for installation, and the other for administration (setting the parameters).

The way it works is that we add the parameter tags to the xml file twice - once in the format expected by Joomla 1.5 and once in the format required by 1.6. When we do this though, although administering the plugin (editing the parameters) works fine, there are problems with actually installing - which is why we need a separate xml file for the installation.

The file that is used by Joomla for administering the plugin parameters must be given the same file name as the plugin. So if your plugin is called "my_plugin", the xml file used for editing parameters must be named "my_plugin.xml".

During installation however, the requirement for the name to be the same as that of the plugin cannot be enforced (because Joomla does not know the name of the plugin until it reads it in the xml file!), so Joomla picks up the first xml file it finds and uses that for the install. Thus, by prefixing the file name with an underscore, Joomla finds that file first, and we can get it to use it for installation ("_my_plugin.xml").

In order to ensure that the administration xml file is added during installation, the installation xml file must include it in the files list. Likewise, in order to ensure that the installation xml file is removed during uninstallation, the administration xml file must include it in its files list (so each xml file includes a reference to the other).

The root tag in the xml file has changed its name from 'install' in Joomla 1.5 to 'extension' in 1.6. Oddly enough, using the new tag name with 1.5 works ok when installing, but fails to uninstall. We therefore have to use the deprecated 'install' tag which currently works ok for installing AND uninstalling in both 1.5 and 1.6. If support for that tag name is dropped in future, then of course this method will not work, and it will probably not be possible to create a single package for all versions of Joomla.

So, to summarise, assuming a plugin called 'my_plugin', here is the file structure:

_my_plugin (a folder)
    _my_plugin.xml
    GPLv2.txt
    my_plugin.php
    my_plugin.xml
my_plugin.php
my_plugin.xml

...and here is what goes in each file

_my_plugin/_my_plugin.xml (the installation manifest for Joomla 1.5 and Joomla 1.6 - parameters are not required, as this file will only be used to install the files - parameters can go in the other manifest file):

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="content">
    <name>My Plugin</name>
    <author>My Name</author>
    <creationDate>July 2010</creationDate>
    <copyright>(C) 2010 My Company Ltd. All rights reserved.</copyright>
    <license>GPL v2.0 (See enclosed file)</license>
    <authorEmail>support@example.com</authorEmail>
    <authorUrl>www.example.com</authorUrl>
    <version>1.0</version>
    <description>My fantastic plugin that does something very clever</description>
    <files>
        <filename plugin="my_plugin">my_plugin.php</filename>
        <filename plugin="my_plugin">my_plugin.xml</filename>
    </files>
</install>

_my_plugin/GPLv2.txt: text of the GPL license should be distributed with the plugin

_my_plugin/my_plugin.php: this is the main code file

_my_plugin/my_plugin.xml (the admin manifest for Joomla 1.5 and Joomla 1.6 - we have to duplicate the parameters, providing them in both Joomla 1.5 and Joomla 1.6 formats):

<?xml version="1.0" encoding="utf-8"?>
<install version="1.6" type="plugin" group="content">
    <name>My Plugin</name>
    <author>My Name</author>
    <creationDate>July 2010</creationDate>
    <copyright>(C) 2010 My Company Ltd. All rights reserved.</copyright>
    <license>GPL v2.0 (See enclosed file)</license>
    <authorEmail>support@example.com</authorEmail>
    <authorUrl>www.example.com</authorUrl>
    <version>1.0</version>
    <description>My fantastic plugin that does something very clever</description>
    <files>
        <filename plugin="my_plugin">my_plugin.php</filename>
        <filename plugin="my_plugin">_my_plugin.xml</filename>
    </files>

    <config>
        <fields name="params">
            <fieldset name="settings" group="settings" label="Settings">
                <field name="my_first_param" type="radio" default="1" label="Do something clever?" description="Whether or not to do some clever stuff">
                    <option value="0">No</option>
                    <option value="1">Yes</option>
                </field>
                <field name="my_second_param" type="radio" default="0" label="Do something stupid?" description="Whether or not to do something silly">
                    <option value="0">No</option>
                    <option value="1">Yes</option>
                </field>
            </fieldset>
        </fields>
    </config>

    <params>
        <param name="my_first_param" type="radio" default="1" label="Do something clever?" description="Whether or not to do some clever stuff">
            <option value="0">No</option>
            <option value="1">Yes</option>
        </param>
        <param name="my_second_param" type="radio" default="0" label="Do something stupid?" description="Whether or not to do something silly">
            <option value="0">No</option>
            <option value="1">Yes</option>
        </param>
    </params>
</install>   

my_plugin.php (the Joomla 1.0 mambot file, which simply needs to include the main code file like this [note: a closing PHP tag ?> is not required and is usually best omitted]):

<?php
include(realpath(dirname(__FILE__)) . "/_my_plugin/my_plugin.php");

my_plugin.xml (the old Joomla 1.0 style manifest file)

<?xml version="1.0" encoding="iso-8859-1"?>
<mosinstall version="1.0" type="mambot" group="content">
    <name>My Plugin</name>
    <author>My Name</author>
    <creationDate>July 2010</creationDate>
    <copyright>(C) 2010 My Company Ltd. All rights reserved.</copyright>
    <license>GPL v2.0 (See enclosed file)</license>
    <authorEmail>support@example.com</authorEmail>
    <authorUrl>www.example.com</authorUrl>
    <version>1.0</version>
    <description>My fantastic plugin that does something very clever</description>
    <files>
        <filename mambot="my_plugin">my_plugin.php</filename>
        <filename mambot="my_plugin">_my_plugin/my_plugin.php</filename>
    </files>
    <params>
        <param name="my_first_param" type="radio" default="1" label="Do something clever?" description="Whether or not to do some clever stuff">
            <option value="0">No</option>
            <option value="1">Yes</option>
        </param>
        <param name="my_second_param" type="radio" default="0" label="Do something stupid?" description="Whether or not to do something silly">
            <option value="0">No</option>
            <option value="1">Yes</option>
        </param>
    </params>
</mosinstall>

Zip it all up, and it should install and uninstall successfully on Joomla 1.0, 1.5, and 1.6. You can download the sample code here.

Comments