(For more resources related to this topic, see here.)
Creating a package
When you are distributing your extensions, often, the problem you are helping your customer solve cannot be achieved with a single extension, it actually requires multiple components, modules, and plugins that work together. Rather than making the user install all of these extensions manually one by one, you can package them all together to create a single install package.
Our click-to-call plugin and folio component go together nicely, so let's package them together.
Create a folder named pkg_folio_v1.0.0 on your desktop, and within it, create a folder named packages. Copy into the packages folder the latest version of com_folio and plg_content_clicktocall, for example, com_folio_v2.7.0.zip and plg_content_clicktocall_v1.2.0.zip.
Now create a file named pkg_folio.xml in the root of the pkg_folio_v1.0.0 folder, and add the following code to it:
<?xml version="1.0" encoding="UTF-8" ?> <extension type="package" version="3.0"> <name>Folio Package</name> <author>Tim Plummer</author> <creationDate>May 2013</creationDate> <packagename>folio</packagename> <license>GNU GPL</license> <version>1.0.0</version> <url>www.packtpub.com</url> <packager>Tim Plummer</packager> <packagerurl>www.packtpub.com</packagerurl> <description>Single Install Package combining Click To Call plugin with
Folio component</description> <files folder="packages"> <file type="component" id="folio" >com_folio_v2.7.0.zip</file> <file type="plugin" id="clicktocall" group="content">plg_content_
clicktocall_v1.2.0.zip</file> </files> </extension>
This looks pretty similar to our installation XML file that we created for each component; however, there are a few differences. Firstly, the extension type is package:
<extension type="package" version="3.0">
We have some new tags that help us to describe what this package is and who made it. The person creating the package may be different to the original author of the extensions:
You will notice that we are looking for our extensions in the packages folder; however, this could potentially have any name you like:
For each extension, we need to say what type of extension it is, what its name is, and the file containing it:
<file type="component" id="folio" >com_folio_v2.7.0.zip</file>
You can package together as many components, modules, and plugins as you like, but be aware that some servers have a maximum size for uploaded files that is quite low, so, if you try to package too much together, you may run into problems. Also, you might get timeout issues if the file is too big. You'll avoid most of these problems if you keep the package file under a couple of megabytes.
You can install packages via Extension Manager in the same way you install any other Joomla! extension:
However, you will notice that the package is listed in addition to all of the individual extensions within it:
Setting up an update server
Joomla! has a built-in update software that allows you to easily update your core Joomla! version, often referred to as one-click updates (even though it usually take a few clicks to launch it). This update mechanism is also available to third-party Joomla! extensions; however, it involves you setting up an update server.
You can try this out on your local development environment. To do so, you will need two Joomla! sites: http://localhost/joomla3, which will be our update server, and http://localhost/joomlatest, which will be our site that we are going to try to update the extensions on. Note that the update server does not need to be a Joomla! site; it could be any folder on a web server.
Install our click-to-call plugin on the http://localhost/joomlatest site, and make sure it's enabled and working. To enable the update manager to be able to check for updates, we need to add some code to the clicktocall.xml installation XML file under /plugins/content/clicktocall/:
<?xml version="1.0" encoding="UTF-8"?> <extension version="3.0" type="plugin" group="content" method="upgrade"> <name>Content - Click To Call</name> <author>Tim Plummer</author> <creationDate>April 2013</creationDate> <copyright>Copyright (C) 2013 Packt Publishing. All rights reserved.
</copyright> <license>http://www.gnu.org/licenses/gpl-3.0.html</license> <authorEmail>firstname.lastname@example.org</authorEmail> <authorUrl>http://packtpub.com</authorUrl> <version>1.2.0</version> <description>This plugin will replace phone numbers with click to call
links. Requires Joomla 3.0 or greater. Don't forget to publish this plugin! </description> <files> <filename plugin="clicktocall">clicktocall.php</filename> <filename plugin="clicktocall">index.html</filename> </files> <languages> <language tag="en-GB">language/en-GB/en-GB.plg_content_clicktocall.
ini</language> </languages> <config> <fields name="params"> <fieldset name="basic"> <field name="phoneDigits1" type="text" default="4" label="PLG_CONTENT_CLICKTOCALL_FIELD_PHONEDIGITS1
DESC" /> <field name="phoneDigits2" type="text" default="4" label="PLG_CONTENT_CLICKTOCALL_FIELD_PHONEDIGITS2_
DESC" /> </fieldset> </fields> </config> <updateservers> <server type="extension" priority="1" name="Click To Call Plugin Updates">http://localhost/joomla3
/updates/clicktocall.xml</server> </updateservers> </extension>
The type can either be extension or collection; in most cases you'll be using extension, which allows you to update a single extension, as opposed to collection, which allows you to update multiple extensions via a single file:
When you have multiple update servers, you can set a different priority for each, so you can control the order in which the update servers are checked. If the first one is available, it won't bother checking the rest:
The name attribute describes the update server; you can put whatever value you like in here:
name="Click To Call Plugin Updates"
We have told the extension where it is going to check for updates, in this case http://localhost/joomla3/updates/clicktocall.xml. Generally, this should be a publically accessible site so that users of your extension can check for updates. Note that you can specify multiple update servers for redundancy.
Now on your http://localhost/joomla3 site, create a folder named updates and put the usual index.html file in it. Copy it in the latest version of your plugin, for example, plg_content_clicktocall_v1.2.1.zip. You may wish to make a minor visual change so you can see if the update actually worked. For example, you could edit the en-GB.plg_content_clicktocall.ini language file under /language/en-GB/, then zip it all back up again.
PLG_CONTENT_CLICKTOCALL_FIELD_PHONEDIGITS1_LABEL="Digits first part"
PLG_CONTENT_CLICKTOCALL_FIELD_PHONEDIGITS1_DESC="How many digits in
the first part of the phone number?"
PLG_CONTENT_CLICKTOCALL_FIELD_PHONEDIGITS2_LABEL="Digits last part"
PLG_CONTENT_CLICKTOCALL_FIELD_PHONEDIGITS2_DESC="How many digits in
the second part of the phone number?"
Now create the clicktocall.xml file with the following code in your updates folder:
<?xml version="1.0" encoding="utf-8"?> <updates> <update> <name>Content - Click To Call</name> <description>This plugin will replace phone numbers with click to
call links. Requires Joomla 3.0 or greater. Don't forget to publish this plugin! </description> <element>clicktocall</element> <type>plugin</type> <folder>content</folder> <client>0</client> <version>1.2.1</version> <infourl title="Click To Call Plugin 1.2.1">http://packtpub.com
</infourl> <downloads> <downloadurl type="full" format="zip">http://localhost/joomla3
/updates/plg_content_clicktocall_v1.2.1.zip</downloadurl> </downloads> <targetplatform name="joomla" version="3.1" /> </update> </updates>
This file could be called anything you like, it does not need to be the extensionname.xml as long as it matches the name you set in your installation 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. Also, if your extension supports both Joomla! 2.5 and Joomla! 3, you will need to have separate <update> definitions for each version. And if you want to support updates for both Joomla! 3.0 and Joomla! 3.1, you will need separate tags for each of them.
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>Content - Click To Call</name>
The value of the description tag is shown 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 jos_extensions table in your database:
The value of the type tag describes whether this is a component, module, or a plugin:
The value of the folder tag is only required for plugins, and describes the type of plugin this is, in our case a content plugin. Depending on your plugin type, this may be system, search, editor, user, and so on.
The value of the client tag describes the client_id in the jos_extensions 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 it's a frontend or a backend module:
Plugins must have <folder> and <client> elements, otherwise the update check won't work.
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 updates to be shown:
The the infourl tag is optional, and allows you to show a link to information about the update, such as release notes:
<infourl title="Click To Call Plugin 1.2.1">http://packtpub.com</
The downloads tag shows all of the available download locations for the update.
The value of the Downloadurl tag is the URL to download the extension from. This file could be located anywhere you like, it does not need to be in the updates folder on the same site. The type attribute describes whether this is a full package or an update, and the format attribute defines the package type such as zip or tar:
<downloadurl type="full" format="zip">http://localhost/joomla3/
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, you can use min_dev_level and max_dev_level in here, but in most cases you'd want your update to be available for all Joomla! versions in that Joomla! release. Note that min_dev_level and max_dev_level are only available in Joomla! 3.1 or higher.
<targetplatform name="joomla" version="3.1" />
So, now you should have the following files in your http://localhost/joomla3/updates folder.
You can make sure the XML file works by typing the full URL http://localhost/joomla3/updates/clicktocall.xml:
As the update server was not defined in our extension when we installed it, we need to manually add an entry to the jos_update_sites table in our database before the updates will work.
So, now go to your http://localhost/joomlatest site and log in to the backend. From the menu navigate to Extensions | Extension Manager, and then click on the Update menu on the left-hand side. Click on the Find Updates button, and you should now see the update, which you can install:
Select the Content – Click To Call update and press the Update button, and you should see the successful update message:
And if all went well, you should now see the visual changes that you made to your plugin.
These built-in updates are pretty good, so why doesn't every extension developer use them? They work great for free extensions, but there is a flaw that prevents many extension developers using this; there is no way to authenticate the user when they are updating. Essentially, what this means is that anyone who gets hold of your extension or knows the details of your update server can get ongoing free updates forever, regardless of whether they have purchased your extension or are an active subscriber.
Many commercial developers have either implemented their own update solutions, or don't bother using the update manager, as their customers can install new versions via extension manager over the top of previous versions. This approach although is slightly inconvenient for the end user, it is easier for the developer to control the distribution.
One such developer who has come up with his own solution to this, is Nicholas K. Dionysopoulos from Akeeba, and he has kindly shared his solution, the Akeeba Release System, which you can get for free from his website and easily integrate into your own extensions. As usual, Nicholas has excellent documentation that you can read if you are interested, but it's beyond the scope of this book to go into detail about this alternative solution (https://www.akeebabackup.com/products/akeeba-release-system.html).
Now you know how to package up your extensions and get them ready for distribution. You learnt how to set up an update server, so now you can easily provide your users with the latest version of your extensions.
Resources for Article:
- Tips and Tricks for Joomla! Multimedia [Article]
- Adding a Random Background Image to your Joomla! Template [Article]
- Showing your Google calendar on your Joomla! site using GCalendar [Article]