Additions:

Deletions:

---

Additions:

Deletions:

---

Packaging for Aliro add-ons

Aliro comes with an easy-to-use universal installer for add-ons. Technically, these may be Applications, Modules, Plugins, Components, Templates or others. “Others” are specialized installation units, including patches. Aliro will handle packages that contain multiple add-on objects, each of which has its own XML setup file. Whatever the type of the extension to be installed, the process is identical. Using the universal installer, the site administrator can add a feature or a template (or a package containing multiple items) by uploading a single archived file. The installer does the rest.

Packaging is done by creating a directory structure that corresponds to the intended directory structure after installation. The only complication is that some add-ons install files to both the user part of the Aliro CMS directory structure and also to the administrator part. For packaging, the destination is ignored, and files are placed together. This means that it is not possible to have files or directories with the same names (at the same levels) in both user and administrator areas. At the top level of files, there must be an XML file to define what is in the package and what should be done with it. The XML file is described in detail below.

The whole directory structure, including both the files that make up the add-on and the XML packaging file are turned into an archive (the installer will handle either .zip or .tar.gz archives) using standard tools. The archive can contain a top level directory provided it is the only directory at the top level and there are no files at the same level. The installer will simply drop into a single top level directory, or work at the top level of the archive. If there are multiple XML files, they will all be processed allowing multiple add-ons to be installed in a single package. Although a better solution may be the "application" type of add-on.

Important design note: So as to maximize security, it is a strict design policy for Aliro that ALL code needed on the user side should be placed in user side directories. Put another way, any code that is common to both user and administrator must be placed on the user side. It should also NOT be assumed that the top level directory for the administrator side is called "administrator". Aliro will run happily with other names and it is expected that add-ons should do the same. For the time being it is very likely that most sites will actually call the directory "administrator" but the aim is the break this dependence on a particular name. Note that code running on the user side will (intentionally) find it quite difficult to locate the adminstrator directory and classes that are located on the administrator side will not be automatically loaded when running on the user side. An implication of this design feature may be that some quite powerful facilities have to be implemented in user side code, but particularly critical operations should be confined to access through the administrator login. Although not part of packaging, for reference, details of the path information available to the whole CMS (including add-ons) are given in [[AliroBasicSymbols] [Aliro basic symbol definitions]].

The XML Setup File

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://www.aliro.org/xml/extsinstall.dtd"∞>
or alternatively:
<!DOCTYPE mosinstall SYSTEM "http://www.aliro.org/xml/mosinstall.dtd"∞>
These DOCTYPE statements refer to DTD files at the Aliro web site. 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 web site. 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, <extinstall> or <mosinstall>. The name “mosinstall” derives from Mambo Open Source, which is a precursor to Aliro. Either tag can be used and they will be treated in the same way – the appropriate DTD file must be used, and they are identical apart from the outmost tag. The <mosinstall> tag is supported to make it easier to utilize software written for other systems, such as Mambo 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. Again, this is to ease migration of software from one CMS platform to another. There is a corresponding DTD file called install.dtd. Installation of software meant for other CMS may not immediately work, but attempting it can provide a helpful start to migration.
The <extinstall> or <mosinstall> element supports the following attributes:
type – mandatory and must be one of component, module, plugin, mambot, template, language, patch, include, parameters, menu (note that “plugin” and “mambot” mean the same).
version – the lowest version of Aliro for which the extension can be validly installed – currently ignored.
client – optional, and if present must be either administrator or user. For extensions that exists specifically on either the administrator or user side of the system, such as a module, this attribute should be specified. If omitted, user is assumed.
userclass – optional, but see adminclass below – this is the name of the class to be instantiated when the extension is invoked on the user side
adminclass – optional and is the name of the class to be instantiated when the extension is invoked on the administration side – if neither userclass nor adminclass are specified, the extension is assumed to be written in the style required by Joomla 1.0.x or Mambo 4.x
menuclass – optional for components and is the class to be invoked when a new menu entry is being created for the component – it allows for the creation of a variety of different kinds of menu entries to carry out different functions in the component
triggers – mandatory for mambots and is a comma separated list of the event names for which the mambot is to be activated
published – optional for mambots and modules and may be set equal to “yes” - in which case the extension will be immediately published without any action by the admnistrator
inner – optional for templates, and may be set to “yes” - indicates a template that is used for an area within the browser window, unlike a standard template that defines the entire window.

XML elements that are common to all types of installation are listed below: 
<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 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 formal name from the ordinary name. The addition of formalname is intended to make the labeling of extensions more transparent.
<version>
The version of the package.
<description>
A brief description of the Component, Module, Template or Mambot. Note that if this contains any HTML it must be enclosed as CDATA. For an example of this, please see below.
<creationdate>
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>
The name of the author of the extension.
<authorurl>
The author's URL.
<authoremail>
The email address of the author.
<copyright>
Copyright information affecting the extension.
<license>
The license under which the extension is being released.
<warning>
Included for compatibility but has no function at present.
<credits>
Included for compatibility but has no function at present.
<group>
Included for compatibility, but has no function at present.
<files>
Optional, the <files> 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>
Similar to <files> except that the individual <filename> entries within <classfiles> are expected to have the “classes” attribute which defines what class names are included in a file. If an entry within a <classfiles> section does not have the “classes” attribute, an error message will be shown. To fully utilize Aliro, all PHP code files should be included here.
<images>
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>
Similar to <files> except that CSS files should be included here for clarity
<media>
Similar to <files> except that the files included here should be material such as images that are treated as data by the extension
<langfiles>
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, 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. Where this feature is used (and its use is recommended) the file must be in the specified subdirectory in the install package and will 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 – is a comma separated list giving the names of classes that are included within the file. The information is stored in the classmap table and used by Aliro's smart class loader to make classes available as they are invoked. The classes named in the userclass or adminclass tags of the <mosinstall> element must appear within the classes attribute of some <filename> element. Class names must be unique across the system, so it is advisable to make sure each class has a prefix belonging to the extension that is not used by other developers. If the extension manages its own code loading, this attribute may be omitted, but use of Aliro's smart class loader is highly recommended
Where a <filename> element appears in the XML of a language package, it will have a number of other attributes (domain, strings, translated, fuzzy, percent, 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, 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, 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 on an uninstallation it will be executed. Any SQL specified within an <uninstall> element will also be run after the uninstall file has been run.
<upgradefile>
Applies only to a component, 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 on an upgrade it will be executed. Note that the XML does not include provision for SQL queries on upgrade because 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 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, which in turn may contain <menu> elements which will be displayed to the administrator as a submenu.
<params>
Defines parameters used by the extension, and is described in more detail below.
<locale>
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. Always automatically generated by the language processing in Aliro, so further details are not given here.
Parameters
Extension setup files may also have a group of elements defining parameters, for example:
This is a generalised 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. It can have the following attributes:
name – will be used as the key to hold parameter information as an associative array
type – indicates the type of parameter and can have any of these values: text, list, radio, imagelist, textarea, editarea, dynamic, spacer. There are others retained for backwards compatibility, but they are deprecated in favour of using “dynamic”. The types are explained in detail below.
directory – is used in association with the “imagelist” type to define a directory from which all images will be offered as a list from which a selection can be made.
default – is the default value to be assigned if no choice is made.
label – is the text that will be used to label the field when values are being invited for this parameter
description – will be linked to the entry of this parameter as a tooltip or some other device that gives extra information to the person entering parameter data.
class – refers to the name of a singleton class and is only used in connection with the “dynamic” type of parameter
method – again only used with the “dynamic” type of parameter, and refers to the method to be used after the static method “getInstance” has been used against the specified class to obtain an object
other – it is possible for the “dynamic” type of parameter to implement other attributes specific to the context
<option>
Where 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.
Parameter types
text – allows the entry of a string of text on one line
list – provides a “menu” of items (defined by <option> tags) from which one choice can be made
radio – provides a set of choices (defined by <option> tags) shown as radio buttons
imagelist – gives a list of images from which one can be selected – must be associated with a “directory” attribute that defines a directory (relative to the document root) that contains a set of images
textarea – similar to “text” but creates an input area rather than a single line
editarea – similar to “textarea” but invokes the system WYSIWYG editor rather than only allowing plain text (if no editor is installed, Aliro will provide a null editor and this parameter type will drop down to being a textarea)
dynamic – supports arbitrary extensions to the parameter system for use by extensions. It must be associated with “class” and “method” attributes. The class is taken as a class name that is assumed to be a singleton and to implement the “getInstance” static class method. Once “getInstance” has been used against the class name to obtain an object, the method specified is called with the following parameters:
name – the name of the parameter, which is also the key to be used in the associate array that implements the set of parameters
value – the current value of the parameter
controlname – the overall name to be used for values entered into the parameter block, with controlname subscripted by name
param – the PHP SimpleXML element that corresponds to this parameter – so that the method can extract further attributes if desired.
spacer – produces a horizontal rule or similar division between parameters, but does not define a parameter as such