Using the installer API to support package installation - Revision history

VisiGod: changed "lang" to "language" in the area "The language files"

2009-10-10T02:37:07Z

changed "lang" to "language" in the area "The language files"

Jedbox: /* Packaging */

2009-03-29T19:00:05Z

‎Packaging

Masterchief at 04:28, 9 July 2008

2008-07-09T04:28:39Z

Chris Davenport: Removed external link. Added note about DTD's not being usable in 1.5

2008-07-06T10:08:22Z

Removed external link. Added note about DTD's not being usable in 1.5

Erikfinnegan at 10:15, 5 July 2008

2008-07-05T10:15:06Z

Erikfinnegan at 10:11, 5 July 2008

2008-07-05T10:11:34Z

Erikfinnegan at 10:09, 5 July 2008

2008-07-05T10:09:34Z

Erikfinnegan: New page: == Packaging == [http://www.mjaztools.com/ MjazTools] have come up with a [http://extensions.joomla.org/component/option,com_mtree/task,writereview/link_id,2421/Itemid,35/ contribution] i...

2008-07-05T09:57:00Z

New page: == Packaging == [http://www.mjaztools.com/ MjazTools] have come up with a [http://extensions.joomla.org/component/option,com_mtree/task,writereview/link_id,2421/Itemid,35/ contribution] i...

New page

== Packaging ==

[http://www.mjaztools.com/ MjazTools] have come up with a [http://extensions.joomla.org/component/option,com_mtree/task,writereview/link_id,2421/Itemid,35/ contribution] including an [http://ant.apache.org/ Ant] build script to package your development result into an archive for distribution.

The script needs to be extended for sorting your files into folders within the archive, which are needed for the Joomla! extension installer API. See the recommended file locations below:

{| border=1 cellspacing=0 cellpadding=2
|-
! Development file
! Archive folder
|-
| <tt>/components/com_<component name>/**</tt>
| <tt>/site/**</tt> (mimic folder structure)
|-
| <tt>/adminsitrator/components/com_<component name>/**</tt>
| <tt>/admin/**</tt> (mimic folder structure)
|-
| <tt>/language/en-GB/en-GB.com_<component name>.ini</tt>
| <tt>/language/site</tt> (flatten structure: discard language code subfolders)
|-
| <tt>administrator/language/en-GB/en-GB.com_<component name>.ini</tt>
| <tt>/language/admin</tt> (flatten structure: discard language code subfolders)
|-
| <tt>install.<component name>.php</tt>
| /
|-
| <tt>uninstall.<component name>.php</tt>
| /
|-
| <tt>install.<component name>.sql</tt>
| /admin
|-
| <tt>uninstall.<component name>.sql</tt>
| /admin
|-
| <tt><component name>.xml</tt> '''The manifest file'''
| /
|}

== The Component Manifest File ==

Your component needs an xml-file declaring meta data (author, license, etc.), which files are included and indicates some special files to the installer API, like the included languages and SQL-scripts for (un)installing.

The most important xml-elements are explained below. For a full syntax refer to [http://dev.joomla.org/xml/1.5/component-install.dtd the manifest's DTD]:

=== The root element ===

<install type="''component|module|...''" method="''upgrade''">
<name>''component name''</name>
<version>''x.y''</version>
...

Enter the '''type''' of your extension, and indicate whether the installer shall be able to overwrite existing files. If the '''method''' attribute is not given, the installer will quit gracefully when encountering any existing file on the webspace.

=== The file list ===

<install>
<files folder="site">
<folder>''views''</folder>
...
<filename>''component-name.php''</file>
...

<administration>
<files folder="admin">
...

List all files which make up the code of your component, which will later go to the <tt>component</tt> subfolder of the site. Same for the administration part.

=== The language files ===

<install>
<languages folder="lang/site">
<language tag="''en-GB''">en-GB.com_''<component name>''.ini</language>
...

<administration>
<languages folder="lang/admin">
<language ...

The language files for the front-end will be copied to the respective language code subfolders. Same for the administration part.

=== SQL scripts ===

<install>
<install>
<sql>
<file driver="''mysql''">''install.component.sql''</file>
</sql>
</install>
<uninstall>
<sql>
<file driver="''mysql''">''uninstall.component.sql''</file>
</sql>
</uninstall>

If you need tables added or altered for your component, put the statements into an sql script. The sql statements will be executed by the installer after copying of the files. Do not forget to indicate '''the way back''' and develop a script for cleaning up when the components shall be uninstalled.

=== Custom install code ===

<install>
<installfile>install.component.php</installfile>
<uninstallfile>uninstall.component.php</uninstallfile>

The code in these files will be executed by the installer upon install/uninstall. See API description below.

== Custom Installer Code API ==

If you need more to be done to the live site upon (un)installation than deploying the files, languages, and executing SQL statements, the installer files are your way. For example, you might need to update existing data entries in the tables during an upgrade installation. The code will be executed after deployment.

The scrips should have exactly one function:

<source lang=php>
function com_install()
</source>

@@ Line 1: / Line 1: @@
 {{review}}
 {{joomla version category|1.5}}
-[[Category:Developers]]
+[[Category:Development]]
 == Packaging ==

← Older revision		Revision as of 10:11, 5 July 2008
Line 1:		Line 1:
	{{review}}		{{review}}
		+	{{joomla version category\|1.5}}
	[[Category:Developers]]		[[Category:Developers]]

← Older revision		Revision as of 10:09, 5 July 2008
Line 1:		Line 1:
		+	{{review}}
		+	[[Category:Developers]]
		+
	== Packaging ==		== Packaging ==

@@ Line 72: / Line 72: @@
   <install>
-      <languages folder="lang/site">
+      <languages folder="language/site">
           <language tag="''en-GB''">en-GB.com_''<component name>''.ini</language>
           ...
       <administration>
-          <languages folder="lang/admin">
+          <languages folder="language/admin">
               <language ...

@@ Line 14: / Line 14: @@
 | <tt>/site/**</tt> (mimic folder structure)
 |-
-| <tt>/adminsitrator/components/com_<component name>/**</tt>
+| <tt>/administrator/components/com_<component name>/**</tt>
 | <tt>/admin/**</tt> (mimic folder structure)
 |-

@@ Line 4: / Line 4: @@
 == Packaging ==
 The script needs to be extended for sorting your files into folders within the archive, which are needed for the Joomla! extension installer API. See the recommended file locations below:
@@ Line 46: / Line 43: @@
 Your component needs an xml-file declaring meta data (author, license, etc.), which files are included and indicates some special files to the installer API, like the included languages and SQL-scripts for (un)installing.
-The most important xml-elements are explained below. For a full syntax refer to [http://dev.joomla.org/xml/1.5/component-install.dtd the manifest's DTD]:
+The most important xml-elements are explained below.  There is a [http://dev.joomla.org/xml/1.5/component-install.dtd manifest DTD for Joomla! 1.5 components] which can be used as a guide to the syntax, but it cannot be used to validate the manifest due to a problem with the 1.5 component installer.  This should be corrected for Joomla! 1.6 onwards.
 === The root element ===

@@ Line 111: / Line 111: @@
 == Custom Installer Code API ==
-If you need more to be done to the live site upon (un)installation than deploying the files, languages, and executing SQL statements, the installer files are your way. For example, you might need to update existing data entries in the tables during an upgrade installation. The code will be executed after deployment.
+If you need more to be done to the live site upon (un)installation than deploying the files, languages, and executing SQL statements, the installer files are your way. For example, you might need to update existing data entries in the tables during an upgrade installation. Indicate the scripts in the manifest file (see above), and the code will be executed after deployment.
-The scrips should have exactly one function:
+The install script should define exactly one function:
 <source lang=php>
 function com_install()
 </source>