All installations using the installer require a text file written in XML. The XML file contains information about the extension, which is retained for display in the administration part of the site. It also contains directives that tell the installer how to handle the installation. Only a passing familiarity with XML is required since the structure is quite simple. Each XML file begins with the prologue, <?xml version="1.0" encoding="utf-8" ?>.

It is also a good idea to include a DOCTYPE as the second line of the XML file. It could be:

<!DOCTYPE extinstall SYSTEM " http://aliro.org/xml/extinstall.dtd">

This DOCTYPE statement refers to a DTD file at the Aliro website. Including a DOCTYPE means that the XML file can be checked using a choice of online XML validators. If the validator says that the XML is correct, then it should work with Aliro. If there is a problem with the XML, Aliro will issue detailed diagnostics.

With every XML file submitted as part of an installation, Aliro will look for the outermost tag, and if it is recognized, the DOCTYPE will be replaced (or inserted, if not present) with a reference to one of the local DTD files included with the Aliro installation. This avoids any delays during validation through having to access a remote website. Note that the installation process does strict validation of the XML and will not complete an installation where the XML does not conform to the DTD. Strict XML checking includes a requirement that elements and attributes appear in the order of the specification.

After the initial XML line and the DOCTYPE (if present), several nested sections appear, all of which are within the root element, <extinstall>. For backwards compatibility, Aliro will also accept <mosinstall> which derives from Mambo Open Source, which is a precursor to Aliro. Either tag can be used, but newer features will only be accepted within <extinstall>. The <mosinstall> tag is supported to make it easier to utilize software written for other systems, such as Mambo, MiaCMS, or Joomla!

In fact, Aliro will also handle a file whose outermost tag is <install> and will assume that it is an XML file for the Joomla! 1.5 system. In this case, the tag is transformed to <josinstall> before being processed, because the Joomla! 1.5 XML is not legal on account of <install> being used both as the outermost element and also as an inner element. Again, this is to ease migration of software from one CMS platform to another. There is a corresponding DTD file called josinstall.dtd. Installation of software meant for other CMS may very well not immediately work, but attempting it can provide a helpful start to migration.

The <extinstall> element supports the following attributes:

XML elements that are common to all types of installation are listed as follows:

<name>

The name element is an informal name for the extension and will be seen by the administrator.

<formalname>

The formalname element is mandatory and must be unique in the installed system. By convention components will have a name of 'com_xxxxx', modules will be 'mod_xxxx', plugins will be 'bot_xxxx', user side templates will be 'ut_xxxx', and admin side templates will be 'at_xxxx' where 'xxxx' is the chosen name. Care should be taken over the selection of formalname. Note that this is an addition relative to Aliro's precursors, although for backwards compatibility Aliro will, with components only, attempt to derive a value for the formalname from the ordinary name. The addition of formalname is intended to make the labeling of extensions more transparent.

<version>

This is the version of the installed package.

<description>

This is a brief description of the component, module, template, or plugin. Note that if this contains any XHTML it must be enclosed as CDATA. This is done by first writing the string <![CDATA[ followed by the XHTML and terminated by the string ]]>.

<creationdate>

This is the creation date for this package. There is no specifically defined format for this date; it is just a string. Simple numeric forms are ambiguous internationally and should be avoided.

<author>

This is the name of the author of the extension.

<authorurl>

This is the author's URL.

<authoremail>

This is the e-mail address of the author.

<copyright>

This is the copyright information affecting the extension.

<license>

This is the license under which the extension is being released.

<warning>

This is included for compatibility but has no function at present.

<credits>

This is included for compatibility but has no function at present.

<group>

This is included for compatibility, but has no function at present.

<module>

An application is allowed to define integrated modules. Attributes should be applied to tell the framework about the module. They can be userclass, adminclass, client, and published, and have the same meanings as when used as attributes of <extinstall>. Where a class is given, it can simply be the name of a class, or it can be the class name followed by a comma and a method name. If no method is supplied, the default activate will be used. This element can contain <name>, <formalname>, <description>, and <params> elements, which are all described here.

<plugin>

An application is also allowed to define integrated plugins. Attributes can be userclass, triggers, and published. There is no distinction between user and administrator plugins, otherwise the userclass functions as for integrated modules. The triggers attribute works just as it does when applied to <extinstall> (described earlier). Contained elements are the same as for an integrated module.

<urilink>

An application can also specify <urilink> elements to give a direct connection between the received URI and the application. These elements can have attributes class, published, template, and html. Contained elements are <name>, <description> and <uri>. The first two of these function as elsewhere, and <uri> contains a regular expression that will be matched against the URI, after the domain has been removed. Briefly, if the URI matches the given regular expression, the specified class will be activated. The <published> element operates as for modules or plugins. It is possible to indicate with the template attribute (which can be yes or no and defaults to yes) whether the response should include a whole page via template processing, or only the output of the class invoked by the link. It is also possible to define through the html attribute (also defaults to yes) whether the output should be wrapped with the usual <html> page structure, or output with no addition at all. The latter is suitable where, for instance, the link is being used to dynamically deliver something like an image.

<files>

This is optional, and this section is used to tell the installer which files it should install. The <files> element can contain an arbitrary number of <filename> sections. Each of the major extension types has its own distinct directory within an Aliro installation (some have one directory for user side and one for administration side). An extension will be given its own directory named with the <formalname> value, one reason why there is a requirement for uniqueness. To fully utilize Aliro, only files that do not fall into any of the following categories should be included here.

<classfiles>

This is similar to <files> except that the individual <filename> entries within <classfiles> are expected to refer to files that contain PHP code, probably including classes. Files that are listed here will be parsed and information about contained classes will be used for automatic loading.

<images>

This is similar to <files> except images that are used in by the extension as essential to its normal functioning (for example, needed as part of the browser screen display) should be included in this section for clarity.

<css>

This is similar to <files> except that CSS files should be included here for clarity.

<media>

This is similar to <files> except that the files included here should be material, such as images that are treated as data by the extension.

<langfiles>

This is similar to <files> except that the individual <filename> entries within <langfiles> are expected to refer to a gettext PO file and the file name should be a language in the standard form of, for example, 'es' or 'fr-CA' which defines the language and possibly the region for which the file gives translations, followed by the .po extension. For components, the language files are stored by the installer in the user side component directory, using any subdirectory information implied by the <filename> entry.

<filename>

Any of the file holding elements (that is files, classfiles, images, css, media, or langfiles) must contain one or more <filename> elements. The filename is given within this entry and can be preceded by one or more directory levels, each one separated from others and from the filename by a forward slash. Wherever this feature is used (and its use is recommended) the file must be in the specified subdirectory in the install package and should be placed in the corresponding subdirectory in the Aliro installation. The <filename> element has an important attribute when it occurs within a <classfiles> section:

classes: This was a comma separated list giving the names of classes that are included within the file. Its use is now deprecated, and the information provided is ignored by Aliro, since the files are parsed to obtain information about classes.

Wherever a <filename> element appears in the XML of a language package, it will have a number of other attributes such as domain, strings, translated, fuzzy, percent, and filetype but these are not described here because the XML files for language are always created automatically by Aliro.

<install>

This element brackets a <queries> element, which in turn contains an arbitrary number of <query> elements. When the extension is installed, each SQL query within a <query> element inside the <install> element will be executed.

<uninstall>

This operates in exactly the same way as <install> except that it applies to the removal of the extension. Note that unlike its predecessors, Aliro's installer caters for upgrades, so it is reasonable to include in the <uninstall> element SQL to completely remove the data for the extension.

<installfile>

Applies only to a component or application, and specifies a file in the same way as the <filename> element. On an installation, the file will be moved to the administrator component directory and executed.

<uninstallfile>

Applies only to a component or application, and specifies a file in the same way as the <filename> element. On an installation, the file will be moved to the administrator component directory, and it will be executed when the component or application is uninstalled. Any SQL specified within an <uninstall> element will also be run after the uninstall file has been run.

<upgradefile>

Applies only to a component or application, and specifies a file in the same way as the <filename> element. On an installation or upgrade, the file will be moved to the administrator component directory, and on an upgrade it will be executed. Note that the XML does not include provisions for SQL queries on upgrade as it is assumed that more logic is required to determine exactly what SQL actions are appropriate according to the circumstances. The logic can more effectively be placed in the PHP of the upgrade file.

<administration>

The <administration> element is used only for components and applications and may include a <files> element to specify files that will be placed in the administration side components directory. It may also include an <images> element on the same basis. In addition, it can contain one or more <menu> elements. The <menu> element is described in more detail below. It can also contain a <submenu> element.

<menu>

The menu element can appear within the <administration> element, or within a <submenu> element (see below). It specifies the text that is to go into the administrator's menu of applications. The link for the menu entry is determined by the attributes, which can be act, task, or link.

<submenu>

An extension into a submenu can be achieved by including a <submenu> element in the <administration> element. It contains one or more <menu> elements that will be used to form a submenu.

<params>

This defines parameters used by the extension, and is described in more detail in the next section.

<locale>

This is used only in the XML for language packages, and always has the attributes name, title, territory, locale, text_direction, iso639, iso3166_2, iso3166_3, and charset. It is always automatically generated by the language processing in Aliro, so further details are not given here.

Extension setup files may also have a group of elements defining parameters, for example:

<params>
<param name="menu_image"
type="imagelist"
directory="/images/stories"
hide_default="1"
default=""
label="Menu Image"
description="A small image to be placed to the left or right of your menu item, images must be in images/stories/" />
<param name="pageclass_sfx"
type="text"
size="20"
default=""
label="Page Class Suffix"
description="A suffix to be applied to the css classes of the page, this allows individual page styling" />
<param name="back_button"
type="list"
default=""
label="Back Button"
description="Show/Hide a Back Button, that returns you to the previously view page">
<option value="">Use Global</option>
<option value="0">Hide</option>
<option value="1">Show</option>
</param>
<param name="header"
type="text"
size="30"
default=""
label="Page Title"
description="Text to display at the top of the page" />
<param name="page_title"
type="radio"
default="1"
label="Page Title" description="Show/Hide the Page title">
<option value="0">Hide</option>
<option value="1">Show</option>
</param>
</params>

This is a generalized XML-driven system that allows for easy creation of sets of parameters. A set of parameters is implemented as an associative array and is normally stored in the database by being serialized. The XML provides enough information for the creation of a screen block that invites the entry of values for all the parameters identified in the XML. The XML can include defaults and the entry can be through an input field, or can be a choice of specified options. There are only three tag types here, but a number of attributes are available for the <param> tag. The tags are:

<params>

The main tag to define a set of parameters.

<param>

The tag for an individual parameter can have the following attributes:

<option>

Wherever the type of the <param> is list or radio then two or more <option> tags need to be included within the <param> tag. Each option has a value that is the text to be shown against the choice and each option has an attribute value which determines the actual value to be stored in the associative array if this option is chosen.