Documentation

Packaging

Download (pdf)

Overview

It is possible to install a component manually by copying the files using an SFTP client and modifying the database tables. It is more efficient to create a package file in the form on an XML document that will allow the Installer to do this for you. This package file contains a variety of information:

  • basic descriptive details about your component (i.e. name), and optionally, a description, copyright and license information.
  • a list of files that need to be copied.
  • optionally, a PHP file that performs additional install and uninstall operations.
  • optionally, an SQL file which contains database queries that should be executed upon install/uninstall

Note: All components must be prefixed with com_.

Manifest

This XML file just outlines basic information about the component such as the owner, version, etc. for identification by the installer and then tells the installer which files should be copied and installed.

A typical component manifest:

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.5.0">
	<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>

	<!-- Custom Install Script to execute -->
	<!-- Note: This will be copied from the root of the installation package to the administrator directory automatically -->
	<installfile>install.eventlist.php</installfile>

	<!-- Custom Uninstall Script to execute -->
	<!-- Note: This will be copied from the root of the installation package to the administrator directory automatically -->
	<uninstallfile>uninstall.eventlist.php</uninstallfile>

	<!-- Install Database Section -->
	<install>
		<sql>
			<file driver="mysql" charset="utf8">install.mysql.utf8.sql</file>
			<file driver="mysql">install.mysql.nonutf8.sql</file>
		</sql>
	</install>

	<!-- Uninstall Database Section -->
	<uninstall>
		<sql>
			<file driver="mysql" charset="utf8">uninstall.mysql.utf8.sql</file>
			<file driver="mysql">uninstall.mysql.nonutf8.sql</file>
		</sql>
	</uninstall>

	<!-- Site Main File Copy Section -->
	<files>
		<filename>index.html</filename>
		<filename>test.php</filename>
		<folder>views</folder>
	</files>

	<!-- Site Main Language File Copy Section -->
	<languages>
		<language tag="en-GB">en-GB.com_test.ini</language>
		<language tag="de-DE">de-DE.com_test.ini</language>
		<language tag="nl-NL">nl-NL.com_test.ini</language>
	</languages>

	<!-- Site Main Media File Copy Section -->
	<media destination="com_test">
		<filename>image.png</filename>
		<filename>flash.swf</filename>
	</media>

	<administration>
		<!-- Administration Menu Section -->
		<menu img="components/com_test/assets/test-16.png">EventList</menu>
		<submenu>
			<!-- Note that all & must be escaped to & for the file to be valid XML and be parsed by the installer -->
			<menu link="option=com_helloworld&task=hello&who=world">Hello World!</menu>
			<!-- Instead of link you can specify individual link attributes -->
			<menu img="icon" task="hello" controller="z" view="a" layout="b" sub="c">Hello Again!</menu>
			<menu view="test" layout="foo">Testing Foo Layout</menu>
		</submenu>

		<!-- Administration Main File Copy Section -->
		<!-- Note the folder attribute: This attribute describes the folder
				to copy FROM in the package to install therefore files copied
				in this section are copied from /admin/ in the package -->
		<files folder="admin">
			<filename>index.html</filename>
			<filename>admin.test.php</filename>
		</files>

		<!-- Administration Language File Copy Section -->
		<languages folder="admin">
			<language tag="en-GB">en-GB.com_test.ini</language>
			<language tag="de-DE">de-DE.com_test.ini</language>
			<language tag="nl-NL">nl-NL.com_test.ini</language>
		</languages>

		<!-- Administration Main Media File Copy Section -->
		<media folder="admin" destination="com_test">
			<filename>admin-image.png</filename>
			<filename>admin-flash.swf</filename>
		</media>
	</administration>
</extension>

Structure

Packaging a component for distribution is relatively easy. The file and directory structure is exactly as it would be after installation. For example, all front-end files are places within a directory called /site and all administration files are placed within a directory called /admin. Here's what a typical package will look like:

/com_{componentname}
  {componentname}.xml
  /site
    {componentname}.php
    controller.php
    /views
      /{viewname}
        /tmpl
          default.php
    /models
      {modelname}.php
    /controllers
      {controllername}.php
  /admin
    {componentname}.php
    controller.php
    /views
      /{viewname}
        /tmpl
          default.php
    /models
      {modelname}.php
    /controllers
      {controllername}.php

Just "zip" up the primary directory into a compressed archive file. When the ZIP file is installed, the language file is copied to /app/bootstrap/{client}/language/{LanguageName}/{LanguageName}.{ComponentName}.ini and is loaded each time the module is loaded. All of the other files are copied to the /app/components/{ComponentName} directory of the installation.

Last modified: