001b. Adding an update server and a changelog

Adding an update server and a change log

In this chapter we will ...

Surely you will develop your component further. How do you make sure that your customers always use the latest version? How do they know about an update? Now that we have built an Joomla! extension, we need to consider how we will maintain it.

Since Joomla! 2.5.4 there is a possibility in Joomla! to offer updates for extensions. Also, a Joomla! Core Update can be made directly from the back end without having to download and upload the package itself.

This chapter explains how to create and run an update server for your component.

Update Server sounds a bit complicated, basically it's just a URL to an XML file specified in the installation XML file. This XML file then contains a number of details, including the new version and the download URL which Joomla! can read out. If Joomla! finds an update this will be displayed in the back end.

In the next picture you can see this update note in the section Extensions | Update. Since Joomla 4.0, extension developers can leverage the ability of Joomla to read a changelog file and give a visual representation of the changelog. If a given version is not found in the changelog, the changelog button will not be shown. You only see the text N/A.

Extensions Update

In the next picture there is a changelog for the new version.

Extensions Update test Administration

What has changed in the last update shows you the Manage View in the Extension Manager.

Extensions Manage test Administration

And in the last picture you can see what the changelog looks like.

Extensions Manage test Administration(1)

Joomla! has a built-in update software that allows you to easily update your core Joomla! version. This update mechanism is also available to third-party Joomla! extensions. However, you need to set up an update server.

You can try this out on your local development environment. To do so, you will need a Joomla! site, which will be your site that you are going to try to update the extension on. The update server could be any folder on your local web server.

Install version 1.0.0 of our component. To enable the update manager to be able to check for updates, you need to create a new version.

<dlid prefix="dlid=" suffix="" /> You have to enter an update key here: http://localhost/JOOMLA/administrator/index.php?option=com_installer&view=updatesites

Newly created or Modified files

Newly created files

changelog.xml

foo_update.xml

Modified files

administrator/components/com_foos/foos.xml

All changes at a glance

Click here to see all changes compared to the last chapter.

More detailed explanations

Newly created files

changelog.xml

<changelogs>
	<changelog>
		<element>com_foos</element>
		<type>component</type>
		<version>1.0.0</version>
		<note>
			<item>Initial Version</item>
		</note>
	</changelog>
	<changelog>
		<element>com_foos</element>
		<type>component</type>
		<version>1.0.1</version>
		<security>
			<item><![CDATA[<p>No security issues.</p>]]></item>
		</security>
		<fix>
			<item>No fix</item>
		</fix>
		<language>
			<item>English</item>
		</language>
		<addition>
			<item>Change log and Update Server added.</item>
		</addition>
		<change>
			<item>No change</item>
		</change>
		<remove>
			<item>No remove</item>
		</remove>
		<note>
			<item>Change log and Update Server added.</item>
		</note>
	</changelog>
</changelogs>

See https://github.com/joomla/joomla-cms/pull/24026 and https://docs.joomla.org/Adding_changelog_to_your_manifest_file for more information concerning the changelog.

foo_update.xml

You have told your component in the file administrator/components/com_foos/foos.xml where it is going to check for updates.

Now create the file foo_update.xml with the following code. The file could be called anything you like as long as it matches the name you set in the installation XML administrator/components/com_foos/foos.xml for the extension.

The updates tag surrounds all the update elements. Each time you release a new version, you will need to create another update section.

If your extension supports other Joomla! versions, you will need to have separate <update> definitions for each version.

<updates>
    <update>

The value of the name tag is shown in the Extension Manager Update view, so using the same name as your extension should avoid confusion:

        <name>com_foos</name>

The value of the description tag is shown when you hover over the name in the update view.

        <description>This is com_foo</description>

The value of the element tag is the installed name of the extension. This should match the value in the element column in the #__extensions table in your database.

        <element>com_foos</element>

The value of the type tag describes what extension that is, for example whether this is a component, module, or a plugin.

        <type>component</type>

The value of the version tag is the version number for this release. This version number needs to be higher than the currently installed version of the extension for available update to be shown.

        <version>1.0.1</version>

The changelogurl tag is optional, and allows you to show a link to inform about the changes in this release - you created this file before in this chapter.

		<changelogurl>https://raw.githubusercontent.com/astridx/boilerplate/tutorial/changelog.xml</changelogurl>

The infourl tag is optional, and allows you to show a link to inform about the update or a release note.

    <infourl title="agosms">https://github.com/astridx/boilerplate/blob/v1.0.1/README.md</infourl>

The downloads tag shows all of the available download locations for an update.
The value of the downloadurl tag is the URL to download the extension form. This file could be located anywhere you like.
The type attribute describes whether this is a full package or an update, and the format.
And the format attribute defines the package type such as zip or tar.

        <downloads>
            <downloadurl type="full" format="zip">https://github.com/astridx/boilerplate/releases/download/v1.0.1/com_foos-1.0.1.zip</downloadurl>
        </downloads>

The tags maintainer and maintainerurl are are self-explanatory.

        <maintainer>Foo Creator</maintainer>
        <maintainerurl>http://www.example.com</maintainerurl>

The targetplatform tag describes the Joomla! version this update is meant for. The value of the name attribute should always be set to joomla.

If you want to target your update to a specific Joomla! version your update to a specific Joomla! version you can use min_dev_level and max_dev_level in here.

        <targetplatform name="joomla" version="4.*"/>

Sometimes you want your update to be available for a minimum PHP Version. If you want to target a minimum PHP-Version you can do this with the tag php_minimum.

	<php_minimum>7.1</php_minimum>

So, now you can close all tags.

    </update>
</updates>

For plugins you need to add a tag named folder and a tag named client. This tags are only required for plugins. The tag folder describes the type of plugin this is. Depending on your plugin type, this may be system, content, search, and so on. The value of the client tag describes the client_id in the #__extension table, which tells Joomla! if this is a site (0) or an administrator (1) extension type. Plugins will always be 0, components will always be 1; however, modules could vary depending on whether they are a front end or a back end module.