Actions

Difference between revisions of "Deploying an Update Server"

From Joomla! Documentation

(client tag required for front-end modules)
(make it clear that client is required for modules)
(15 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{RightTOC}}
+
{{version/tutor|2.5,3.x}}
  
This tutorial is for all Joomla! versions newer than {{JVer|1.6}}
+
== Introduction ==
 +
This tutorial is designed to teach developers how to create an update server for integration with the update system introduced in Joomla!.  By adding an update server listing to your extension's manifest, developers enable users to update their extensions via the Extension Manager's Update (see [[Help25:Extensions Extension Manager Update|Joomla 2.5]] and [[Help31:Extensions Extension Manager Update|Joomla 3.x]] helpscreens) view with only a few clicks.
  
= Introduction =
+
== Defining an update server ==
This tutorial is designed to teach developers how to create an update server for integration with the update system introduced in Joomla! 1.6By adding an update server listing to your extension's manifest, developers enable users to update their extensions via the [[Help16:Extensions Extension Manager Update|Extension Manager's Update]] view with only a few clicks.
+
In order to use this feature, an update server must be defined in your extension's manifest.  This definition can be used in all Joomla! 2.5 and newer compatible extensions but is not available for templatesYou can use two options for your server type; collection or extension.  These will be explained in detail shortly.  This code should be added to the extension manifest file, within the root "extension" element. The update server is defined as follows for each type:
  
= Defining an update server =
+
<source lang="xml">
In order to use this feature, an update server must be defined in your extension's manifest. This definition can be used in all Joomla! 1.6 and newer compatible extensions but is not available for templates. You can use two options for your server type; collection or extension. These will be explained in detail shortly.  The update server is defined as follows for each type:
+
<extension>
 
+
  <...>
<code>
+
 
  <updateservers>
 
  <updateservers>
 
     <server type="collection">http://example.com/list.xml</server>
 
     <server type="collection">http://example.com/list.xml</server>
 
     <server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
 
     <server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
 
  </updateservers>
 
  </updateservers>
</code>
+
</extension>
 +
</source>
  
 
Multiple servers can be defined within the <updateservers> tag.
 
Multiple servers can be defined within the <updateservers> tag.
  
= Server types =
+
== Server types ==
== Collection ==
+
=== Collection ===
 
The collection server type allows developers to define an extension's manifest to pull updates from a collection.  This type of server can be used if the developer wants to define all of their extension's updates in a single file (not recommended) or if their extension has multiple sub-extensions which are not distributed or updated at the same time (such as a package extension type).  The below example is the collection definition used by the updater when processing core Joomla! updates:
 
The collection server type allows developers to define an extension's manifest to pull updates from a collection.  This type of server can be used if the developer wants to define all of their extension's updates in a single file (not recommended) or if their extension has multiple sub-extensions which are not distributed or updated at the same time (such as a package extension type).  The below example is the collection definition used by the updater when processing core Joomla! updates:
  
<code>
+
<source lang="xml">
 
  <extensionset name="Joomla Core" description="Joomla! Core">
 
  <extensionset name="Joomla Core" description="Joomla! Core">
 
     <extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="http://update.joomla.org/core/extension.xml"/>
 
     <extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="http://update.joomla.org/core/extension.xml"/>
 
  </extensionset>
 
  </extensionset>
</code>
+
</source>
  
 
All definitions must be defined between <extensionset> tags in your collection manifest.  The <extensionset> tag has two optional parameters; name and description.  For each extension that this collection references, a separate <extension> tag is required.  The <extension> tag has the following parameters, all of which are required for updates to properly process:
 
All definitions must be defined between <extensionset> tags in your collection manifest.  The <extensionset> tag has two optional parameters; name and description.  For each extension that this collection references, a separate <extension> tag is required.  The <extension> tag has the following parameters, all of which are required for updates to properly process:
Line 36: Line 37:
 
* '''detailsurl''' - The URL of the XML file which contains that extension's individual update definitions
 
* '''detailsurl''' - The URL of the XML file which contains that extension's individual update definitions
  
== Extension ==
+
=== Extension ===
 
The extension server type allows developers to define an extension's manifest to pull updates from a single extension's manifest.  All collection manifests eventually point to this XML file.  All updates in this file must be defined after an <updates> tag at the beginning of the file.  The below example is the update definition for the Joomla! 1.7.0 release:
 
The extension server type allows developers to define an extension's manifest to pull updates from a single extension's manifest.  All collection manifests eventually point to this XML file.  All updates in this file must be defined after an <updates> tag at the beginning of the file.  The below example is the update definition for the Joomla! 1.7.0 release:
  
<code>
+
<source lang="xml">
 
  <update>
 
  <update>
 
     <name>Joomla! 1.7</name>
 
     <name>Joomla! 1.7</name>
Line 58: Line 59:
 
     <targetplatform name="joomla" version="1.6"/>
 
     <targetplatform name="joomla" version="1.6"/>
 
  </update>
 
  </update>
</code>
+
</source>
  
 
The following section describes the elements of a single update entity.
 
The following section describes the elements of a single update entity.
Line 64: Line 65:
 
* '''name''' - The name of the extension, this name will appear in the Name column of the Extension Manager's Update view (required)
 
* '''name''' - The name of the extension, this name will appear in the Name column of the Extension Manager's Update view (required)
 
* '''description''' - A short description of the extension (optional) -- if you choose to use <![CDATA[]]>, double-quotes will break the HTML formatting.  Use single quotes with your HTML entities.
 
* '''description''' - A short description of the extension (optional) -- if you choose to use <![CDATA[]]>, double-quotes will break the HTML formatting.  Use single quotes with your HTML entities.
* '''element''' - The installed name of the extension (required)
+
* '''element''' - The installed name of the extension (required). For plugins, this needs to be same as plugin attribute value for main file in plugin manifest. For <filename plugin="pluginname">pluginname.php</filename>, element value should be '''pluginname'''.
 
* '''type''' - The type of extension (component, module, plugin, etc.) (required)
 
* '''type''' - The type of extension (component, module, plugin, etc.) (required)
 
* '''folder''' - Specific to plugins, this tag describes the type of plugin being updated (content, system, etc.) (required for plugins)
 
* '''folder''' - Specific to plugins, this tag describes the type of plugin being updated (content, system, etc.) (required for plugins)
* '''client''' (usually optional, required for J! 1.7.3 due to a regression; but highly encouraged regardless) - The client ID of the extension, which can be found by looking inside the #__extensions table. To date, use 0 for "site" and 1 for "administrator". Plugins and front-end modules are automatically installed with a client of 0 (site), but you will need to specify the client in an update or it will default to 1 (administrator) and then found update would not be shown because it would not match any extension. Components are automatically installed with a client of 1, which is currently the default.
+
* '''client''' Required for modules as of 3.2.0. - The client ID of the extension, which can be found by looking inside the #__extensions table. To date, use 0 for "site" and 1 for "administrator". Plugins and front-end modules are automatically installed with a client of 0 (site), but you will need to specify the client in an update or it will default to 1 (administrator) and then found update would not be shown because it would not match any extension. Components are automatically installed with a client of 1, which is currently the default.
 
** ''Warning'': The tag name is <'''client'''> for Joomla! 2.5 and <'''client_id'''> for 1.6 and 1.7. If you use <client_id> (rather than <client>) on a 2.5 site, it will be ignored.
 
** ''Warning'': The tag name is <'''client'''> for Joomla! 2.5 and <'''client_id'''> for 1.6 and 1.7. If you use <client_id> (rather than <client>) on a 2.5 site, it will be ignored.
 
* '''version''' - The version of the release (required)
 
* '''version''' - The version of the release (required)
Line 82: Line 83:
 
** '''name''' - The name of the platform dependency; as of this writing, it should ONLY be "joomla"
 
** '''name''' - The name of the platform dependency; as of this writing, it should ONLY be "joomla"
 
** '''version''' - The version of Joomla! the extension supports
 
** '''version''' - The version of Joomla! the extension supports
*** '''Note:''' If your extension is Joomla! 1.6, 1.7, and/or 2.5 compatible, you will be required to have separate <update> definitions for each version due to the manner in which the updater checks the version
+
** '''min_dev_level''' and '''max_dev_level''' - These attributes were added in 3.0.1 to allow you to select a target platform based on the developer level ("z" in x.y.z). They are optional. You can specifiy either one or both. If omitted, all developer levels are matched. For example, the following matches versions 4.0.0 and 4.0.1. <code><targetplatform name="joomla" version="4.0" min_dev_level="0" max_dev_level="1"/></code>
 +
*** '''Note:''' If your extension is Joomla! 2.5 and/or 3.1 compatible, you will be required to have separate <update> definitions for each version due to the manner in which the updater checks the version if you specify a number. However to show your extension on all Joomla versions that support automatic updates add <code><targetplatform name="joomla" version=".*"/></code>. If you want your extension to show on all {{JVer|3.x}} versions then rather than specifying a version in the version tag add in <code><targetplatform name="joomla" version="3.[012345]"/></code>. This will show the update to all 3.x versions.
  
 
A separate <update> definition will be required for each version of your extension you release.
 
A separate <update> definition will be required for each version of your extension you release.
Line 88: Line 90:
 
The values of '''element''', '''type''', '''client_id''' and '''folder''' should match those in the table #__extensions.
 
The values of '''element''', '''type''', '''client_id''' and '''folder''' should match those in the table #__extensions.
  
= Troubleshooting =
+
'''Important for plugins:''' Plugins have to include <folder> and <client> elements to work properly
 +
 
 +
== Troubleshooting ==
 
* '''SQL update script is not executed during update.'''  
 
* '''SQL update script is not executed during update.'''  
 
:If the SQL update script (for example, in the folder <code>sql/updates/mysql</code>) does not get executed during the update process, it could be because there is no version number in the <code>#__schemas</code> table for this extension ''prior to the update''. This value is determined by the last script name in the SQL updates folder. If this value is blank, no SQL scripts will be executed during that update cycle. To make sure this value is set correctly, make sure you have a SQL script in this folder with its name as the version number (for example, 1.2.3.sql if the version is 1.2.3). The file can be empty or just have a SQL comment line. This should be done in the old version -- the one before the update. Alternatively, you can add this value to the <code>#__schemas</code> using a SQL query.  
 
:If the SQL update script (for example, in the folder <code>sql/updates/mysql</code>) does not get executed during the update process, it could be because there is no version number in the <code>#__schemas</code> table for this extension ''prior to the update''. This value is determined by the last script name in the SQL updates folder. If this value is blank, no SQL scripts will be executed during that update cycle. To make sure this value is set correctly, make sure you have a SQL script in this folder with its name as the version number (for example, 1.2.3.sql if the version is 1.2.3). The file can be empty or just have a SQL comment line. This should be done in the old version -- the one before the update. Alternatively, you can add this value to the <code>#__schemas</code> using a SQL query.  
  
= Supporting Tools =
+
== Supporting Tools ==
 
Maintaining your update server files can be difficult depending on the manner in which you set up your files.  An extension which can help you to maintain this is the Akeeba Release System, available free of charge from https://www.akeebabackup.com
 
Maintaining your update server files can be difficult depending on the manner in which you set up your files.  An extension which can help you to maintain this is the Akeeba Release System, available free of charge from https://www.akeebabackup.com
  
= Contributors =
+
== Contributors ==
 
*[[User:mbabker|Michael Babker]]
 
*[[User:mbabker|Michael Babker]]
 +
*[[User:Renekorss|Rene Korss]]
 +
[[Category:Development]]

Revision as of 19:27, 11 November 2013

Contents

Introduction

This tutorial is designed to teach developers how to create an update server for integration with the update system introduced in Joomla!. By adding an update server listing to your extension's manifest, developers enable users to update their extensions via the Extension Manager's Update (see Joomla 2.5 and Joomla 3.x helpscreens) view with only a few clicks.

Defining an update server

In order to use this feature, an update server must be defined in your extension's manifest. This definition can be used in all Joomla! 2.5 and newer compatible extensions but is not available for templates. You can use two options for your server type; collection or extension. These will be explained in detail shortly. This code should be added to the extension manifest file, within the root "extension" element. The update server is defined as follows for each type:

 <extension>
 <...>
 <updateservers>
    <server type="collection">http://example.com/list.xml</server>
    <server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
 </updateservers>
 </extension>

Multiple servers can be defined within the <updateservers> tag.

Server types

Collection

The collection server type allows developers to define an extension's manifest to pull updates from a collection. This type of server can be used if the developer wants to define all of their extension's updates in a single file (not recommended) or if their extension has multiple sub-extensions which are not distributed or updated at the same time (such as a package extension type). The below example is the collection definition used by the updater when processing core Joomla! updates:

 <extensionset name="Joomla Core" description="Joomla! Core">
    <extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="http://update.joomla.org/core/extension.xml"/>
 </extensionset>

All definitions must be defined between <extensionset> tags in your collection manifest. The <extensionset> tag has two optional parameters; name and description. For each extension that this collection references, a separate <extension> tag is required. The <extension> tag has the following parameters, all of which are required for updates to properly process:

  • name - The name of the extension
  • element - The untranslated extension name i.e. mod_custom
  • type - The extension type (component, module, plugin, etc.)
  • version - The latest version of the extension
  • detailsurl - The URL of the XML file which contains that extension's individual update definitions

Extension

The extension server type allows developers to define an extension's manifest to pull updates from a single extension's manifest. All collection manifests eventually point to this XML file. All updates in this file must be defined after an <updates> tag at the beginning of the file. The below example is the update definition for the Joomla! 1.7.0 release:

 <update>
    <name>Joomla! 1.7</name>
    <description>Joomla! 1.7 CMS</description>
    <element>joomla</element>
    <type>file</type>
    <version>1.7.0</version>
    <infourl title="Joomla!">http://www.joomla.org/</infourl>
    <downloads>
        <downloadurl type="full" format="zip">http://joomlacode.org/gf/download/frsrelease/15279/66552/Joomla_1.6.5_to_1.7.0_Package.zip</downloadurl>
    </downloads>
    <tags>
        <tag>stable</tag>
    </tags>
    <maintainer>Sam Moffatt</maintainer>
    <maintainerurl>http://sammoffatt.com.au</maintainerurl>
    <section>Testing</section>
    <targetplatform name="joomla" version="1.6"/>
 </update>

The following section describes the elements of a single update entity.

  • name - The name of the extension, this name will appear in the Name column of the Extension Manager's Update view (required)
  • description - A short description of the extension (optional) -- if you choose to use <![CDATA[]]>, double-quotes will break the HTML formatting. Use single quotes with your HTML entities.
  • element - The installed name of the extension (required). For plugins, this needs to be same as plugin attribute value for main file in plugin manifest. For <filename plugin="pluginname">pluginname.php</filename>, element value should be pluginname.
  • type - The type of extension (component, module, plugin, etc.) (required)
  • folder - Specific to plugins, this tag describes the type of plugin being updated (content, system, etc.) (required for plugins)
  • client Required for modules as of 3.2.0. - The client ID of the extension, which can be found by looking inside the #__extensions table. To date, use 0 for "site" and 1 for "administrator". Plugins and front-end modules are automatically installed with a client of 0 (site), but you will need to specify the client in an update or it will default to 1 (administrator) and then found update would not be shown because it would not match any extension. Components are automatically installed with a client of 1, which is currently the default.
    • Warning: The tag name is <client> for Joomla! 2.5 and <client_id> for 1.6 and 1.7. If you use <client_id> (rather than <client>) on a 2.5 site, it will be ignored.
  • version - The version of the release (required)
  • infourl - A URL to point users to containing information about the update (optional) (In CMS 2.5, if set, this URL will be displayed in the update view)
  • downloads - The section which lists all download locations
    • downloadurl - The URL to download the extension from; the <downloadurl> tag has two required parameters:
      • type - The type of package (full or upgrade)
      • format - The format of the package (zip, tar, etc.)
  • tags - Optional (unknown use)
  • maintainer - The name of the extension maintainer (similar to the <author> tag in a manifest) (optional)
  • maintainerurl - The website of the extension maintainer (similar to the <authorUrl> tag in a manifest) (optional)
  • section - Optional (unknown use)
  • targetplatform - A tag to define platform requirements, requires the following elements
    • name - The name of the platform dependency; as of this writing, it should ONLY be "joomla"
    • version - The version of Joomla! the extension supports
    • min_dev_level and max_dev_level - These attributes were added in 3.0.1 to allow you to select a target platform based on the developer level ("z" in x.y.z). They are optional. You can specifiy either one or both. If omitted, all developer levels are matched. For example, the following matches versions 4.0.0 and 4.0.1. <targetplatform name="joomla" version="4.0" min_dev_level="0" max_dev_level="1"/>
      • Note: If your extension is Joomla! 2.5 and/or 3.1 compatible, you will be required to have separate <update> definitions for each version due to the manner in which the updater checks the version if you specify a number. However to show your extension on all Joomla versions that support automatic updates add <targetplatform name="joomla" version=".*"/>. If you want your extension to show on all Joomla 3.x versions then rather than specifying a version in the version tag add in <targetplatform name="joomla" version="3.[012345]"/>. This will show the update to all 3.x versions.

A separate <update> definition will be required for each version of your extension you release.

The values of element, type, client_id and folder should match those in the table #__extensions.

Important for plugins: Plugins have to include <folder> and <client> elements to work properly

Troubleshooting

  • SQL update script is not executed during update.
If the SQL update script (for example, in the folder sql/updates/mysql) does not get executed during the update process, it could be because there is no version number in the #__schemas table for this extension prior to the update. This value is determined by the last script name in the SQL updates folder. If this value is blank, no SQL scripts will be executed during that update cycle. To make sure this value is set correctly, make sure you have a SQL script in this folder with its name as the version number (for example, 1.2.3.sql if the version is 1.2.3). The file can be empty or just have a SQL comment line. This should be done in the old version -- the one before the update. Alternatively, you can add this value to the #__schemas using a SQL query.

Supporting Tools

Maintaining your update server files can be difficult depending on the manner in which you set up your files. An extension which can help you to maintain this is the Akeeba Release System, available free of charge from https://www.akeebabackup.com

Contributors