You will continue to develop your component. How do you make sure that users always use the latest version? How do they know about an update? Now that the basic framework of the extension is ready, it's important that your users know about enhancements.
In this chapter I will explain how to create and run an update server for your component. If you want to continue working on the features first, I fully understand. Then just skip this section and come back when you publish your extension.
Update Server sounds complicated, it's basically just a URL to an XML file. This URL is inserted in the extension's installation manifest. The XML file contains a number of details, including the new version number and the download URL to the installation file. When Joomla finds an update for an installed extension, this is displayed in the administration area.
For impatient people: Look at the changed program code in the diff view[^codeberg.org/astrid/j4examplecode/compare/t1...t1b] and include these changes in your development version.
Step by step
In the current section, two files are added that are stored outside the website. The addresses or URLs under which these are stored were entered in the previous chapters in the file
<changelogurl>https://codeberg.org/astrid/j4examplecode/raw/branch/tutorial/changelog.xml</changelogurl> <updateservers> <server type="extension" name="Foo Updates">https://codeberg.org/astrid/j4examplecode/raw/branch/tutorial/foo_update.xml</server> </updateservers>
Wondering where to save those files? Perhaps an example is appropriate. Go to the repo https://github.com/astridx/pkg_agadvents. Here you can see the files
changelog.xml. If you click on one of the files, you can call the raw version via a button in the upper right corner. This is
github.com/astridx/pkg_agadvents/blob/master/agadvents-update4.xml. I have included these addresses in the manifest XML file. In the example it is a package. But it is the same for a component, a module or a plugin. The XML file can be found at pkg_agadvents.xml[github.com/astridx/pkg_agadvents/blob/master/j4/pkg_agadvents/src/administrator/manifests/packages/pkg_agadvents.xml].
The changes concerning the changelog and the Joomla Update Server are only mentioned in this chapter. In every other chapter you can update the numbers yourself if this is important to you. If I described this over and over again, it would not only bore you - it would unnecessarily inflate this text.
foo_update.xml (Update Server)
You have told your component in the file administrator/components/com_foos/foos.xml where to find out about updates. That is in the file
Create the file foo_update.xml. The file can be named anything as long as it matches the name you specified in the installation XML administrator/components/com_foos/foos.xml.
updates surrounds all update elements. Create another update section each time you release a new version.
If your extension supports other Joomla versions, create separate
<update>definitions for each version.
The value of
name will be displayed in the Extension Manager Update view. If you use the same name as the extension, you avoid confusion:
The value of the
description tag is displayed when you hover over the name in the Update view.
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.
The value of the
type tag describes what extension it is, e.g. whether it is a component, a module or a plugin.
The value of the tag
version is the version number for this version. This version number must be higher than the currently installed version of the extension in order for the available update to be displayed.
changelogurl is optional and allows to display a link informing about the changes in this version. This file is also the subject of this chapter.
infourl is optional and allows you to display a link that informs about the update or a version note.
downloads shows all available download locations for an update.
The value of the tag
downloadurl is the URL to download the extension. This file can be located anywhere.
type describes whether it is a full package or an update, and the format.
And the attribute
format defines the package type like
maintainerurl are self-explanatory.
targetplatform describes the Joomla version for which this update is intended. The value of the attribute
name should always be set to "joomla":
<targetplatform name="joomla" version="4.*"/>.
If you create your update for a specific Joomla version you can use
Sometimes you want your update to be available for a minimum PHP version. Do this with the tag
At the end, close all tags
For plugins, add a tag called
folderand a tag called
client. These tags are only needed for plugins.
folder describes the type of plugin. Depending on the plugin type, this can be
search, for example.
The value of the
client tag describes the
client_id in the database table
#__extensions. The value for plugins is always
0, components are always
1. Modules and Templates, however, may vary depending on whether it is a frontend
0 or a backend
Below you can see the complete file.
<!-- https://raw.githubusercontent.com/astridx/boilerplate/6f38de563fa487283e2e9d717e4e79445a7e9763/foo_update.xml -> <updates> <update> <name>com_foos</name> <description>This is com_foo</description> <element>com_foos</element> <type>component</type> <version>1.0.1</version> <changelogurl>https://codeberg.org/astrid/j4examplecode/raw/branch/tutorial/changelog.xml</changelogurl> <infourl title="agosms">https://codeberg.org/astrid/j4examplecode/src/branch/v1.0.1/README.md</infourl> <downloads> <downloadurl type="full" format="zip">https://github.com/astridx/boilerplate/releases/download/v1.0.1/com_foos-1.0.1.zip</downloadurl> </downloads> <maintainer>Foo Creator</maintainer> <maintainerurl>http://www.example.com</maintainerurl> <targetplatform name="joomla" version="4.*"/> <php_minimum>7.1</php_minimum> </update> </updates>
Do you like to use a checksum? See the test description in this PR if you don't know how to do this. Under Ubuntu Linux it is possible to calculate the checksum via the console with
sha256sum -b myfile.zipor
sha284sum -b myfile.zip.
Information on the changelog can be found on Github in PR github.com/joomla/joomla-cms/pull/24026 and the Joomla documentation[^docs.joomla.org/adding_changelog_to_your_manifest_file/en]. Below you can see an example file.
// https://raw.githubusercontent.com/astridx/boilerplate/6f38de563fa487283e2e9d717e4e79445a7e9763/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>
You don't know what
<![CDATA[ ... ]]>means? The term CDATA[^en.wikipedia.org/wiki/cdata] is used in the XML markup language for various purposes. It indicates that a given part of the document is general characters rather than program code with a more specific, limited structure. The CDATA section may contain markup characters (
&). These are not interpreted further by the parser. The use of entities such as
&is not necessary.
Only the version number has been adjusted. This change is necessary in every new chapter, because a new function is always added. I do not mention this explicitly in the following.
<authorUrl>[AUTHOR_URL]</authorUrl> <copyright>[COPYRIGHT]</copyright> <license>GNU General Public License version 2 or later;</license> <version>1.0.0</version> <version>1.0.1</version> <description>COM_FOOS_XML_DESCRIPTION</description> <namespace path="src">FooNamespace\Component\Foos</namespace> <scriptfile>script.php</scriptfile>
Test your Joomla component
- install your component in Joomla version 4 to test it:
Copy the files in the
administrator folder into the
administrator folder of your Joomla 4 installation.
Copy the files in the
components folder into the
components folder of your Joomla 4 installation.
A new installation is not necessary. Continue using the files from part 1.
Next, create another version of the example extension. To do this, change the version number in the manifest. Before that, it is not possible to test the update server. Because, there is no update yet. I mention this here anyway, what exactly happens after the creation of the next versions. 3.
if everything works, you will see these displays in front of you after the installation, if you click on the menu
Systemon the left and then select
Extensionin the section
Updateson the right. The image shows the status after version 23.0.0 was released.
System | Update | Extension. Here you will be offered the update for your component. If this is not the case, click on the button
When you open it for the first time you will see the message
The Download Key is missingbecause you have entered the element
dlidin the manifest.
Add a download key via
System | Update Sites. Click on the name of your component. Then you will see the text field in which you can enter any value. At the moment, this value is not checked when the update is retrieved. Save the value.
- if you navigate back to
System | Update | Extension, you will be able to initiate an update or view the changelog.
The update was not possible before because the
Download Keywas not configured.
Find Updatesbutton in the toolbar if the update is no longer displayed.
Deploying an Update Server[^docs.joomla.org/deploying_an_update_server/en]