Learning Joomla! 3 Extension Development: If you have ideas for additional Joomla 3! features, this book will allow you to realize them. It's a complete practical guide to building and extending plugins, modules, and components. Ideal for professional developers and enthusiasts. , Third Edition

There are many ways to extend the functionality of Joomla! using add-on software called extensions. Extensions can be installed on your Joomla! site and they add new functionality, in some cases they change the way your website behaves by overriding the core code.

The three main extension types we are going to cover in this book are plugins, modules, and components, and we will also create a package extension.

Plugins

Plugins are code that run in the background and are triggered by events. When you log onto your Joomla! website, an authentication plugin checks your login credentials and decides whether you should have access to the site or not. Plugins can be used to transform content, such as replacing a tag in an article with a Google map, or cloaking an email address and protecting it from spammers. Plugins can be very powerful, you can also use plugins to override core code and change how Joomla! works.

The following screenshots demonstrate how a plugin replaces an address in an article with an actual Google map.

As you can see, the address has been transformed into a Google map showing where the Sydney Opera House is located.

Modules

Modules are used to display content at a particular place on your website. Your site template defines various module positions that determine where these modules are displayed. The menu of your website is a module, and if you have a small login form, that would also be a module. You might even have a social media module to display your Facebook or Twitter news feed. There are both frontend and backend modules, and often modules work in conjunction with components to display information on your website. Some developers use modules as a workaround to bring library code in, for example, RocketTheme's RokNavMenu, but that is not really what they should be used for. The following screenshot is of a login module:

Components

Components are the apps of the Joomla! world and the most complex extension type. Components are displayed in the main content area of the site, which is often the largest area in the template. Most menu items load a page with a component and there is only one component displayed on the page at a time. Most components have database tables to store or retrieve information. Components generally have a frontend and a backend just like Joomla!, although there are some tools that focus on the backend with nothing displayed on the frontend of the site, for example, Akeeba Admin Tools. You can enhance components using modules and plugins; for instance, you may have a search plugin that allows you to search for the content stored in your component, or a module that displays the latest items for the component. The following screenshot shows one of the core components called com_content; you will see this screen when you are creating an article from the front end of your site:

Languages

Joomla! is used worldwide by many people whose first language is not English. Many websites need to be displayed in the local language of the audience and some even need to support multiple languages. A language pack includes the files necessary to translate the text used on the site. This translates predefined language strings used by core Joomla! or its extensions; it does not translate the article text, on the fly, into another language. We are not going to cover language packs in this book, but we will see how we can translate your extension into multiple languages. The following screenshot shows the control panel menu when the Dutch (NL) language is installed:

Templates

We don't want all our websites to look the same, so Joomla! has a powerful template engine that allows you to install additional templates to change the look and feel of the site. Since the content is separated from the presentation, it is easy to give your site a facelift by simply changing the template, assuming the new template has the same module position names. Every Joomla! website uses at least two templates, a site template for the frontend, and an admin template for the backend. It is also possible to have different pages on the same website using different templates. We are not going to cover templates in this book, as there are plenty of books already dedicated to this subject.

The following screenshot shows the default Joomla! 3 template protostar:

The next screenshot shows exactly the same content with a different template applied, in this case, Beez3, and you can see that this looks very different than the Protostar template.

Libraries

Reusable code libraries, which are a collection of classes, can now be installed in the libraries folder. This is a better way of creating reusable code than putting it in a plugin, as this way the code is only used when needed rather than running in the background waiting for an event trigger. Libraries extension type was introduced in Joomla! 1.6. We are not going to cover the library extension in this book.

What Joomla! version should I develop for? The short answer is definitely Joomla! 3, but probably Joomla! 2.5 as well, while it remains the current long term release.

If you want your extension to have the longest possible shelf life, then supporting Joomla! 3 is essential as its expiry is scheduled for September 2016, compared to Joomla! 2.5 which will have its expiry in September 2014. At the time of writing this book, the Joomla! 2.5 series is the current long term release, which is what most people should be using on their sites, and the long term release of the Joomla! 3 series is to be due out in March 2014.

Joomla! 1.5, while it is still widely in use, has already reached its official end of life which means there will be no more security releases, bug fixes, or improvements added. The Joomla! Extension Directory unpublished all extensions which only support Joomla! 1.5 in March 2013, although they can still be accessed for now at http://archive.extensions.joomla.org/.

Most developers choose to support both Joomla! 2.5 and Joomla! 3, however you need to make the decision as to whether you are going to keep these as separate packages, or just have one code base that supports both versions. There are advantages and disadvantages of both approaches. If you keep separate code bases for different Joomla! versions, then you can take full advantage of any new feature in the newer version and there will be less repetitive code, however, whenever you add a new feature or bug fix, you will need to apply these in two places. If you choose to support both the versions in the same code base, then you need to do more testing to make sure that a feature added for one version doesn't break something in the other version, or that you have a bit of repeated code that does one thing for Joomla! 2.5 and something else for Joomla! 3 – but new features and bug fixes are easier.

The differences between Joomla! 1.5 and Joomla! 2.5 are very dramatic, it was practically a rewrite and people who chose to support both Joomla! 1.5 and Joomla! 2.5 in the same code base were just making it hard on themselves. They either had to dumb down their Joomla! 2.5 versions, making them only use the features from Joomla! 1.5, or they had to rewrite massive chunks of code to backport the functionality. In comparison, the changes between Joomla! 2.5 and Joomla! 3 are relatively minor, and the good news is that since Joomla! 2.5.5, the Joomla! Platform version has been updated which added forward compatibility for some of the new stuff in Joomla! 3, and this makes it easier to support both these versions.

Anyone who wants to support Joomla! 1.5, Joomla! 2.5, and Joomla! 3 in the same code base is just asking for trouble. My advice to you is to start out developing for Joomla! 3 only, and get that functioning perfectly. Then if you choose to also support Joomla! 2.5, you can add in the appropriate code, but don't even bother with Joomla! 1.5.

When developing extensions, it is important to consider the license that you will release the software under. Joomla! is licensed under GNU GPL, which is a popular open source license (http://www.gnu.org/licenses/gpl.html). The GPL license delivers the "four freedoms", that is, to use, study, modify, and distribute software for any purpose.

The GNU GPL is often misunderstood, many people don't understand how something that is free and open source can actually cost money since Joomla! is GPL and doesn't cost anything. You may have heard the explanation for "free" as in freedom as opposed to "free" as in free beer. The GPL allows you to charge for your software if you wish, providing that you make available full unencrypted source code. Of course you can choose to give away your extensions for free if you want to, it is entirely up to you.

GPL gives the user the freedom to make whatever changes they like to the software and it even allows them to distribute the software to other people. The GPL also allows people to fork your extension and potentially even charge other people for this modified version. Hang on a second, why would I want to make my commercial extension GPL if people are just going to give it away or fork it? Well, the simple answer is that if you want your extension to be listed on the Joomla! Extension Directory (JED), then you must license your extension under GPL. Many extension developers receive over 60 percent of their traffic from the JED, so it is quite an incentive. Another major benefit of using the GPL license is that it clearly states that the software has no warranty which can protect the developer.

The GPL does not allow you to sell per domain copies of the software once someone has purchased or is given a copy; they can use it on as many websites as they like. Many developers get round this by charging a per site support fee, and some only provide updates for the purchased number of domains. There is nothing stopping someone purchasing a single site support and then using this same software on multiple domains.

You cannot use encoding or encryption such as ionCube, which many developers used in the past prior to the JED enforcing GPL. In the early days of Joomla!, there were no licensing restrictions and Joomla! extension developers used a wide range of open source and commercial proprietary licenses for their extensions. From July 1, 2009, the JED only listed extensions licensed under the GNU GPL, and at the time of the change, there were a lot of extension developers resistant to it, but more recently developers are seeing the advantages of GPL and are embracing it.

The legal opinion received by Open Source Matters (OSM) is that the PHP code in an extension of Joomla! is considered derivative work and thus must be licensed by GPL. This is why the JED insists on GPL licensing. The requirement for GPL licensing does not apply to JavaScript code, CSS, LESS, images, and documentation.

You can use whatever business model you can think of. One of the great things about Joomla! is that you have a complete freedom of choice. Here are a few popular business models used in the Joomla! community that you may consider when developing extensions:

There are many more business models you can consider, however your individual circumstances and business goals will help you determine which approach is most suitable for you.

Obviously you need a computer to develop Joomla! extensions, but the type of computer you choose is completely up to you. There are free open source software for all the major operating systems, but the most popular operating system in the Joomla! community from my observations at Joomla!Day events seems to be Mac, although personally I use Windows, and there are those that use Linux too. When it comes to Joomla! development, there is no advantage of one operating system over another; you should choose whatever you are most comfortable and familiar with.

You will need to set up a local development environment with a web server, PHP and MySQL, however there are many ways of achieving this. XAMPP is quite popular, and it will work on Windows, Mac, and Linux. There are also a lot of alternatives such as MAMP , WAMP , EasyPHP , and Webmatrix , just to name a few. For Joomla! 3, you should make sure that whichever you choose has PHP Version 5.3.1 or greater, and has MySQL Version 5.1 or greater. Apache webserver is most commonly included in these tools, but there is nothing stopping you from using an alternative webserver such as IIS. You could even set up PHP and MySQL manually if you prefer. You could have no local development environment and just work off a live webserver, but I would not recommend this as it's going to be much faster and more convenient for you to have the local environment, and there is no risk of breaking anything on a live site. Most of these software packages such as XAMPP also include a tool to manage your MySQL database called phpMyAdmin .

To test your code, you will need a web browser, and once again you have many to choose from. I personally like Firefox , but many people develop using Chrome , IE or Safari . I really like the Firebug plugin for Firefox which allows you to inspect elements to see what CSS code is being applied, which is really handy for development purposes. All the major browsers now have some kind of similar development tools, so what you choose to use is entirely up to you. Another great feature of Firefox is the error console, which will help you pinpoint JavaScript errors. You can see the Firebug plugin in the bottom-half part of the following screenshot:

When developing Joomla! extensions, you will need a text editor or an Integrated Development Environment (IDE) to edit the source code. If you are just starting out, try a simple text editor such as Notepad++ or Textedit . The main requirements are that the text editor should support the UTF-8 format and should display line numbers. If you plan to do a lot of development, then an IDE is definitely worth learning. The most popular in the Joomla! community are Eclipse and NetBeans . An IDE has some powerful features that make your life easier and can integrate with Subversion or Git to manage version control. They can also allow you to use a builder such as Phing or Ant to automatically create installable packages for your extensions and simultaneously copy the code to multiple development sites, and they can do file comparisons to see what has changed. Another big advantage of an IDE is that you are able to use a debugging tool such as XDebug to set up breakpoints to step through, and inspect code while it is running. I personally use Eclipse, which can be slow when used on older computers, but if you have a fast processor such as an i7, it works great.

The following screenshot demonstrates how to set Notepad++ preferences to use UTF-8 encoding:

The following screenshot shows where you can turn on line numbers in Notepad++.

The Joomla! coding standards are based on the PEAR coding standards with some small variations. You can see the full details on the developer site at http://developer.joomla.org/5-policies/3-Joomla-Coding-Standards.html.

The first thing to note is that Joomla! uses tabs for indenting and not spaces. The encoding on files must be set to UTF-8, as some other languages need this encoding to display all the different characters, and it is important that Joomla! supports multiple languages.

The closing PHP tag ?> at the end of each file should be left off; your web server is going to automatically handle this, and by leaving it off, you prevent accidental whitespace.

Joomla! uses the Allman style for braces, so the opening brace is on the next line.

if (x == y)
{
  //do something
}

This is unlike the PEAR coding standards which use the K&R style where the opening brace is on the first line.

if (x == y) {
  //do something
}

There are still some minor inconsistencies with the standards used in the core code, but this is improving with each version. It's always best to make your code as similar in style to the core code as possible, as it will make it easier for other people to customize your code to suit their purposes. There is nothing worse than wanting to make a minor change to an extension and finding that the developer's code looks nothing like what you are familiar with, so you waste a lot of time just trying to reverse engineer it. The core components that are mostly like third-party extensions are Weblinks (com_weblinks) and Banners (com_banners); it's a good idea to use these as a reference point. It should be noted that any IDE worth its salt can reformat the code to suit the operator's preference, so minor formatting problems are only really an issue if you are using a basic text editor.

Joomla! uses a Model-View-Controller (MVC) design pattern that separates the data from the presentation. The view displays all the data, but doesn't care how the data is stored; that's the job of the model. The controller tells the model and the views what to do.

New MVC classes were introduced in Joomla! Platform 12.1 which were added to the Joomla! CMS for Joomla! 3 and Joomla! 2.5.5, but these new classes still need a bit of work before they will become widely adopted. Most people are still using the older MVC classes which have been renamed with the Legacy suffix. The core extensions in Joomla! 3 all use JControllerLegacy and JViewLegacy, and we will be focusing on the Legacy classes in this book.

So what is the point of this change? The idea was that the new MVC classes will be used in the CMS in a future version when it adopts Unified Content Model (UCM). The UCM idea is to have a single content structure that would be used for all the extensions, and this will allow them to interact more easily. Essentially, if you develop a comments plugin for one extension, it will automatically work for every other extension due to the consistent data structure. There is still a lot of work that needs to be done to implement UCM, but we may start seeing it around Joomla! 4. There are still not many good examples of the new MVC and the documentation is limited, so my advice is to stick with the legacy classes for now.

The Joomla! CMS roadmap released in March 2013 actually indicates that we will roll MVC legacy classes back to their original names and drop the Legacy suffix. Providing Joomla! continues with its backwards compatibility commitment throughout the Joomla! 3 series, and although the legacy classes may be marked as deprecated, they won't be removed until Joomla! 4.0. Any code we write now for Joomla! 3.1 should continue to work on Joomla! 3.2 and Joomla! 3.5. This MVC rollback may introduce a small backwards compatibility issue for those already using the new MVC that are using type hinting, for example if the new JModel was renamed to JModelInterface, so this is another reason why you wouldn't bother adopting the new MVC classes yet. You can read about the current roadmap at http://developer.joomla.org/cms/roadmap.html.

Using the legacy classes introduces a problem. What if you want to support Joomla! versions prior to Version 2.5.5? For example, Joomla! 2.5.4 doesn't have these legacy classes, so your extension is not going to work on that version. There are workarounds for this, for instance you could create a legacy.php file as follows:

<?php
defined('_JEXEC') or die;

jimport('joomla.application.component.controller');

class JControllerLegacy extends JController
{
}

jimport('joomla.application.component.view');

class JViewLegacy extends JView
{
}

jimport('joomla.application.component.model');

class JModelLegacy extends JModel
{
  public static function addIncludePath($path = '', $prefix = '')
  {
    return parent::addIncludePath($path, $prefix);
  }
}

Then you can load this following code into your component's main PHP file.

if (!class_exists('JControllerLegacy'))
{
  require_once( JPATH_COMPONENT_ADMINISTRATOR.'/legacy.php' );
}

This effectively does what Joomla! 2.5.5 has introduced, where the new legacy classes are an alias for the old ones. If you wanted to use the new MVC classes, then your extension will only be able to support Joomla! 3.0 or greater.

What about Joomla! 1.6 and 1.7, I hear you asking? Well, the above code would possibly make your extension work on these versions too. However there are quite a few other functions that have changed, so you are going to run into other problems. For example, JDate::toMysql() was removed in Joomla! 3 but its replacement JDate::toSql() wasn't introduced until Joomla! 2.5, so you would need to run a slightly different code to support these earlier versions. As Joomla! 1.6 and Joomla! 1.7 are short term releases that have already reached their expiry, and they both have known vulnerabilities, there is no point supporting these versions, and you should encourage anyone using these versions to upgrade to Joomla! 2.5 or even Joomla! 3.

If anyone has told you that all you need to do to upgrade an extension from Joomla! 2.5 to Joomla! 3 is do a find-and-replace for the new legacy classes, then they were lying, or didn't know what they were talking about. This may be true for very simple extensions that are already following best practices, but in reality there is a lot more work involved. There were a number of functions that were deprecated or changed, and with the introduction of Bootstrap, the backend interface has undergone some significant changes. So to make the extension work well on Joomla! 3, there is a bit of work involved.

The following section details a lot of the changes you will need to make to get your extension working in Joomla! 3:

http://docs.joomla.org/Potential_backward_compatibility_issues_in_joomla_3.0_and_Joomla_Platform_12.1

Some of the changes are quite subtle, such as changing the nameQuote to QuoteName, but some require a bit more work than just finding and replacing, such as the changes from getTableFields to getTableColumns. One change I'd like to highlight is the removal of DS that was commonly used for the directory slashes in previous Joomla! versions. Now you should use / instead. For example, JPATH_COMPONENT.DS.'controller.php' would now be written as JPATH_COMPONENT.'/controller.php'. Although you could define a DS constant to avoid having to change your code, I would recommend that you make the effort and update your code.

For plugins and modules, this is probably all you need to do to them and they will work, but for components it is not quite that easy. Even after you've made all these changes, although your extension may work in Joomla! 3, it may not look very pretty. You will see an example of this in the following screenshot, where there are unnecessary bullet points and a field that is only partially showing:

Since Joomla! 3 now uses Bootstrap and is mobile-ready, there is a bit of work required to make the extension look and behave like the core extensions, as there are a number of visual changes such as the introduction of tabs. All the detailed changes necessary to convert a Joomla! 2.5 component to a fully Joomla! 3 native component are outside the scope of this book, but you will be able to compare your code to our Joomla! 3 examples to get an idea of what you need to change, or you could also have a look at com_weblinks. The following screenshot shows the same form as shown in the previous screenshot, however this one has been fully updated to support Joomla! 3:

When you are creating a new extension for Joomla!, should you start from scratch, or fork another similar extension, or use an extension building component? This book is going to cover creating an extension from scratch, so you can learn all the basics. Once you know these, you may wish to fork the extensions we make together or even fork one of your own extensions to save you a lot of time if you need to make something similar.

There are several extension building components that will prompt you for a bit of information, then create a basic component, plugin, or module based on the information you provide. EasyCreator is one such extension that I have used in the past, but you still need to know the basics to be able to modify this automatically generated code to suit your needs. If you want to know more about these types of extension building components, you can refer to the development category within the miscellaneous category on the JED. The JED listing for EasyCreator can be found at http://extensions.joomla.org/extensions/miscellaneous/development/5908.

With regards to forking someone else's extensions, you probably should first approach the developer and discuss your ideas and see if there is an opportunity to work together to make the original extension even better. If the developer has lost interest in further developing the extension or if you have a completely different vision that will take the software down an entirely different path, then there may be an opportunity to fork the extension rather than starting over from scratch.

Now you should have some idea about the differences between a plugin, a module and a component. We discussed what Joomla! version you should support in your development (which is definitely Joomla! 3, and possibly Joomla! 2.5 while it remains the current long term release). We touched on some of the new features of Joomla! 3 such as Bootstrap and jQuery. We talked about why you should use the GNU GPL for your license, and the associated benefit of a JED listing. We discussed some of the common business models used by Joomla! extension developers and then talked about the tools that you will need to use to develop Joomla! extensions. We briefly looked at the coding standards, and then talked about MVC and why we should use the Legacy classes. We talked about upgrading existing Joomla! 2.5 extensions to Joomla! 3, and we also talked about forking. Now get ready for the next chapter where we will start to get our hands dirty with some coding that you can follow along with to create your first Joomla! extension.