Joomla! 1.5 Extensions

Joomla! 1.5 is designed to be augmented and reshaped by means of extension rather than core code modification. Creating extensions can be quite complex, partially because Joomla! 1.5 implements a complex, but generally cohesive, object-oriented design and partially because documentation is sparse, inconsistent, and incomplete.

This note concentrates on the XML manifest files which are used to describe, install, and uninstall four of the five extension types: components, modules, plugins, and templates. The fifth type – languages – does not appear to require a manifest – yet.

WARNING: Use at your own risk. These are my observations after reading the code in <joomla-root>/libraries/joomla/installer/adaptors from the 1.5.3 stable release.

Extension Uses

A relatively easy to understand the differences between the five types of extensions is to how they are used a rendered web page.

A Joomla! web page has a central content area and several areas around the central area (banner across the top, left and right columns, footer, bread-crumb area, etc). We will call the ‘content area’ the Content Area and everything else the Other Stuff. Here’s how things work:

templates – define the structure and implementation of the page. The bulk of the CSS, the outline structure of the HTML, and much of the javascript is defined and maintained in a template. Templates are designed to be interchangable so that the same content and operation of the web site can be ‘re-skinned’ by changing the template. If all of the ‘rules’ are followed, then everything should ‘just work’.
languages – supply translations of web page text into other languages. They are not designed to translate everything in a web page, but rather all the words in the structure of the page. For example, if you page has the word ‘home’ in some of the Other Stuff, it will probably have an entry in a language file which translates it.
components – generate the stuff which goes into the Content Area. components are complete and self contained in that they have their own database tables, mini-templates, language translation files, etc etc. Joomla! 1.5 has adopted the MVC programming model for components – although most of the core components do not yet follow those conventions.
modules – supply HTML for the Other Stuff. modules do not know where they will be placed on a page. Placement is controlled by the Administrator of the site and can be changed at any time. They are responsible for rendering a complete snippet of (X)HTML. They can be simple or complex; they can be stand-alone or supply services for components or plugins. They are the only way to display anything in the Other Stuff parts of a web page.
plugins – Plugins don’t show up explicitly in any part of a rendered page – although their effects probably will. Joomla! 1.5 has a nice event notification system. plugins are chunks of code which register with the notification system and perform event driven tasks. For example, if you want to associate some sort of data with users of our site which is not supplied by a joomla!, you could build a plugin to gather that data and register it for notification. IMO the event notification system – implemented as an Observer/Observable Design Pattern – is a mess because there is no central catalog of events and it appears trivially easy to register an action for an event which will never be triggered. This is a subject for a later note.

Joomla! 1.5 Manifest Files

Of the five types of extensions for Joomla! 1.5, four require manifest files. The manifest file gives complete information about an extension – including:

Authorship – name, contact information
License and Copyright
Versioning
Summary description
file layout
installation / uninstallation instructions
media files

It is formatted as valid XML as defined by the document type definition at: “http://dev.joomla.org/xml/1.5/component-install.dtd”

Manifests are logically structured in N sections. Each section contains zero or more XML elements which should occur in order as defined in the DOCTYPE definition – which is the order they occur in this note.

Overall Structure – Envelope Boilerplate

Application: All

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE install SYSTEM "http://dev.joomla.org/xml/1.5/component-install.dtd">
    <install type="component" version="1.5.0">
    ... contents of manifest ...
    </install>

Everything here is boilerplate and copied verbatum except the install attributes. These required attributes are:

type=”component|module|plugin” – defines the kind of extension this manifest applies to.
version=”minimum joomla version” – in version this is checked using “version_compare($version, ‘1.5’, ‘<’)” to see if legacy support is required.

Metadata Section

Application: All

This section identifies the author, describes the purpose of the extension, and defines the terms of use and ownership. This is pretty straightforward.

    <name>Hello World</name>
    <!-- The following elements are optional and free of formatting conttraints -->
    <creationDate>2007 01 17</creationDate>
    <author>John Doe</author>
    <authorEmail>john.doe@example.org</authorEmail>
    <authorUrl>http://www.example.org</authorUrl>
    <copyright>Copyright Info</copyright>
    <license>License Info</license>
    <!--  The version string is recorded in the components table -->
    <version>Component Version String</version>
    <!-- The description is optional and defaults to the name -->
    <description>Description of the component ...</description>

Notes:

name – is the name of the extension which is displayed in drop-down’s and other places where the administrator needs to select it. It should be something informative.
creationDate – is obviously the date created. There is no Update date and no guidance as to whether or not this should be updated on release revision, etc. Do as you will, but it should make some sort of sense and may be meaningful in a copyright dispute.
authorEmail – self explanatory
authorURL – URL to author’s web site
copyright – copyright . as in: ‘copyright 2008, Joe Blow. All rights reserved’
license – name of license under which others may use the extension. Typically something like: GNU/GPL2 or LGPL2 or Mit License or …
version – your version number. Should be something like 1.0.2 – using the convention: <major> . < release > . patch-number
description – short, concise description of what the extension does, is good for, etc.

Install Element

Application Components ONLY

An install element CONTAINED within the global install element contains queries which create the database files for the component.

In this case, neither the type nor the version attributes are processed. (CHECKTHIS)

It may contain sql or queries elements. At least one sql or queries element must be present, although more than one of both may exist.

Note: queries is deprecated. The preferred joomla! 1.5 method is to use sql files.

    <install>
        <sql>
            <file>name of SQL file</file>
            <file>name of SQL file</file>
        </sql>
    </install>

Uninstall Element

Application: Components ONLY

The uninstall element should drop all the tables created by the install element. Like the install element, it must contain one or more sql and/or queries elements defining how to delete the files.

Note: queries is deprecated. The preferred joomla! 1.5 method is to use sql files.

    <uninstall>
        <sql>
            <file>name of SQL file</file>
            <file>name of SQL file</file>
        </sql>
    </uninstall>

Administrative Section

Application: Components and Templates

Joomla! divides itself into a front end and a back end (or administrative) sections. The manifest reflects this by putting all the back end menu, file, languages, and media inside the administration element.

Components Administration Element

The administration element is required.

    <administration>
        <menu>...</menu>
        <submenu>...</submenu>
        <files>...</files>
        <languages>...</languages>
        <media>...</media>
    </administration>

All sub-elements of the administration element are optional. If present, their contents are copied into subdirectories of joomla! installation as follows:

files – contents copied into <joomla-root>/administator/components/com_<component-name>
languages – contents copied into <joomla-root>/administrator/language/<language-folder>
media – DOESN’T WORK. It is supposed to copy contents into <joomla-root>/media/ but it didn’t do anything when I tested it.
menu and submenu – these items are stuffed into the component table.

Templates Administration Element

    <administration>
        <files>...</files>
        <languages>...</languages>
    </administration>

WARNING: I haven’t tested this, nor have I read the code. I don’t know what this is supposed to do or what it actually does.

Files Element

Application: All

files are closer to the meat of the install. A files element contains filename and folder elements – which are the actual files and directories which make up the extension.

Note: for components only in contrast with the most other elements in the manifest file, you can have more than one files element. This allows groups of files to be sucked out of different source directories. This is probably a good thing if you are building on some other product and want to keep all of its source intact, but doesn’t seem too useful otherwise. [of course, I could be wrong – often am]

Module, plugin, and template installations only process one files element.

    <files folder="source-directory">
        <filename>path to file relative to source-director</filename>
        <folder>path to folder relative to source-directory</folder>
    </files>

Four Notes:

files elements in the administration element are copied into <joomla-root>/administator/<extension-type>/<prefix>_<component-name>. The relative path from this directory is the same as in the filename or folder element. For example, /modules/mod_foobar/file.php
files outside of the administration element are copied to <joomla-root>/<extension-type>/<prefix>_<component-name>. For example, /components/com_foobar/file.php
the name in the filename or folder sub-element is used for the relative path name.
folder sub-elements are copied recursively – that is, it copies everything from the source folder to the destination. If you want to selectively copy files from a source directory, use filename and specify the complete relative path name for each file you want to copy.

Languages Element

Application: All

    <languages folder="source folder">
        <language tag="language identifier">path to language file</language>
    </languages>

languages elements may occur in the main body – in which case they belong to the front end (or site) – or within the administration element.

The folder attribute is optional. As usual, it specifies where the language files are copied FROM.

There must be at least one language element within a languages element. Notice that the tag attribute is required. It specifies the language – and hence the subdirectory of the ‘language’ folder into which the language file will be copied.

The language file path should be simply the file name because the installer will put it away in the correct directory.

Media Element

Application: Component, Module, Plugin

The media specifies image files to copy. It is supposed to work in both the administration and main section [site or front end], but elements in the administration element are ignored.

    <media folder="source folder" destination="destination folder">
        <filename>media file path</filename>
    </media>

Notes:

In my experiments, uninstalling media files did not remove subdirectories, although the image files themselves were removed.
in contrast with files you can only put filename elements within a media element. You can specify full, relative paths to create a directory structure under the destination directory.
if you don’t specify the destination attribute, the files are placed in <joomla-root&gt/media.

Menu and Submenu Elements

Application: Components

Menu elements are a little confusing and I have not installed extensions (or core elements) which use this feature of the manifest file. This is deduced from the code in installer.php. You’ve been warned.

First of all, in spite of the what the component-install.dtd file says, the code in the installer only looks for one (1) direct menu subelement of administration and one (1) submenu direct subelement.

NOTE: both are optional; a reasonable default top level menu entry is created if if the menu element is missing. submenu is only required if there are sub menus.

The Menu Entry

This is used to create the top main menu in the Components Drop Down menu.

    <menu attributes>menu name</menu>

Attributes are:

act –
task -
controller -
view -
layout -
sub -
img -
link -

A menu element may only occur in the administration element. menu element data is used to populate the #__components table.

The menu name is copied into the ‘name’ and ‘admin_menu_alt’ fields.
The img attribute is copied into the ‘admin_menu_img’ field.
all other attributes are ignored

The Submenu Entry

This is used to create Submenu of the top menu in the Components Drop Down Menu

Format is:

    <submenu>
        <menu attributes>first sub menu name</menu>
        <menu attributes>second sub menu name</menu>
        . . .

    </submenu>

For each of the menu elements, element content is used as the menu name and the attributes are used as:

img – admin_menu_img
link – is cleaned and copied to ‘admin_menu_link’
act, task, controller, view, layout, and sub – gathered up as a query string and appended the ‘option=com_<component-name>&’ to select the correct MVC method, view, layout, task, etc

Installfile and Unistallfile Elements

Application: Components ONLY

<installfile>path to installation script file</installfile> <uninstallfile>path to uninstall script file</uninstallfile>

These two elements allow for special scripts to be run during installation and un-installation.

The designated file must be a *php script which contains a function named com_install() and com_uninstall(), respectively.

com_install() is run without arguments after everything in the manifest has been installed, so the function has full access to all of the component’s parts.

Similarly, com_uninstall() is run, without arguments, before anything has been uninstalled from the distribution, so, again, the function has full access to all of the component’s parts. [Note – this makes it useless for removing directories from the media folder]

Params Element

Application: All

The *params element defines zero or more param elements – which (not surprisingly) define parameters.

    <params addParameterDir="path">
        <param attributes>param name OR 
            <option value="some value">option name</option>
        </param>
    </params>

params has a single attribute: adParameterDir – which is ignored by default.

Each param element can have a whole slew of attributes. The installation default action is to discard any param which does not have both a name and default attribute and to ignore the other attributes.

At present, default handling is used for components, modules, and plugins. params are ignored in template installations.

The only possible explanation I can think of is that the manifest files are re-parsed during administrative activities to acquire the parameter lists, attributes, and values necessary to set options for components, modules, plugins, etc.

Module Only Elements

None known

Plugin Only Elements

None known.

Template Only Elements

The ‘necessary elements’

Templates have 3 ‘necessary’ elements: files, images, and css. We’ve already covered files above. Neither images nor css is listed in the DTD file and the code works without either one.

I don’t think the code will work correctly with either images or css elements in the ‘templateDetails.xml’ file because the contents of both should be stuffed into <joomla-root>/templates/<template-name>/images or css/ and the current code will dump them into the template-root directory – i.e. one level up. I guess you could put the appropriate prefixes in the ‘css’ or ‘images’ elements, but you you still have to put in a filename entry for every item. It’s probably legacy code or an option for the future.

NOTE: both ‘css’ and ‘images’ elements are processed by JInstaller::parseFiles() - which returns the number of files processed [0 for css and images] or false on failure. Kindly parseFiles() returns 0 if it can’t find the element it’s asked to process; template.php does an identity (===) compare against false, so everything works. This feels fragile to me.

Positions Element

The positions element lists the positions which modules may occupy in the template. The usual list is [taken from the Milkyway template]:

    <positions>
        <position>breadcrumb</position>
        <position>left</position>
        <position>right</position>
        <position>top</position>
        <position>user1</position>
        <position>user2</position>
        <position>user3</position>
        <position>user4</position>
        <position>footer</position>
        <position>debug</position>
        <position>syndicate</position>
    </positions>