Creating A Simple Joomla! Plugin

—Learn how to build a Joomla plugin that generates Creative Commons licenses for articles.

Published: Monday, October 31 2016 11:38

Written by Jesse Riggs

What Is A Plugin?

A plugin is a software component that adds specific functionality to an existing program. Joomla supports plugins for customized we experience. A Joomla plugin is composed of two parts: an XML model, and a PHP application. The XML piece contains information about a plugin, provides a set of controls, and describes an administration view. The PHP piece contains at lest one event listener which is triggered by a Joomla event.

Motivation

A website administrator wants all content licensed under Creative Commons. Each article will display license information pertaining to the specific article, including: license icon, article title, article author, license type, and article link.

This could easily be achieved by manually appending the appropriate HTML to the end of each article.

However, the site administrator does not want to do this manually to each page. The manual method also leaves room for error. Furthermore, this method is not dynamic. In the case that an article name is changed or migrated to a new domain, the administrator will have to edit the HTML. In the worst case scenario, the administrator will want to change the license terms of the license, in which case each page will have to be edited manually.

So, this project requires that we retrieve server and article information on each page request, and then dynamically generate a license, which will be appended to the article.

The Empty Plugin

To start with, we will create a new plugin, containing a single XML file and a single PHP file, which does nothing, yet. We will then package the package the plugin contents into a tar archive. This archive will be uploaded and installed onto a Joomla server.

Create a new folder called "creativecommons". Create a file called creativecommons.xml, this is our model. Copy the following XML starter code into this file.

What this XML tells Joolmla is that there is an extension of type plugin in group content, and will be installed into the subdirectory plugins/content/. The plugin is named plg_content_creativecommons, and will be listed under extensions with this name. This file also tell Joomla that there is a PHP file associated with this extension, creativecommons.php. There is a tag called fields, which is a set of parameters that will both be shown in the admin view and be passed to creativecommons.php.

Now we will need to define a class inside the PHP file.

This is a simple PHP class with no functions. It is empty. But, this is the framework that we will use to construct a functioning plugin.

Now that we have the two fundamental pieces of a Joomla plugin, we can package them into an archive which can be installed in Joomla. While inside the directory creativecommons, run the following bash command:

This new package can be uploaded and installed from Extensions > Manage > Install > Upload From File. The plugin can now be found under Extensions > Plugins > plg_content_creativecommons.

Adding Prameters

The file creativecommons.xml allows us to add fields which model our plugin's parameters. Joomla uses these fields to construct a set of controls which are displayed in the administrator view. Fields include buttons, lists and categories from which the administrator can choose values to be mapped to their respective field name. At plugin execution, these values will be passed to event handlers as parameters.

Add the following code to creativecommons.xml, under the tag <fieldset name="basic">.

If we inspect the plugin now, we will find new fields to populate; magic. ;)

Events And Handlers

Joomla plugins are triggered by events, so let's look at how this works. Joomla implements an observer design pattern to handle events, at the heart of which is JEventDispatcher. The dispatcher is a subject that maintains a list of observers and updates their states as events are triggered.

JPlugin extends an observer class JEvent such that, when JEventDispatcher is notified of an event, JPlugin will be updated and the appropriate event handler will be called. JPlugin is a useful abstraction which preforms common event tasks for us.

Ordinarily, an observer pattern would require the coder to attach an observer to it's subject.Since plugins are decendents of JEvent, and JEvent is a decendent of JObserver the constructorautomatically attaches the eventhandler object to the dispatcher(which is a JObservable descendant). This means when the Event Handlers are initialized they are automatically added to the observer stack of the dispatcher.

A complete list of Joomla events can be found at https://docs.joomla.org/Plugin/Events. For this plugin, we are looking to append, to article text, a string of HTML. We will use an event which notifies the dispatcher that an article model has been created, and that the article text has been retrieved from the database. For this, we listen for onContentPrepare. When this event is triggered by ContentViewArticle, a reference to an article object will be passed to the dispatcher and then passed to any observer with an onContentPrepare event handler.

Dummy License

Now that we know which event we want to handle, lets throw together a simple dummy license. All we need to do is append some text to the text element of the article argument. Let's add the event handler to our PlgContentCreativeCommons class.

Accessing Parameters

A reference to a composite object called $params is passed from the dispatcher to its observers when an event is triggered. $params contains administrator populated states from control panel. Recall the Adaptations field we added to the file creativecommons.xml, which now displays a list. The list name, cc_adaptations_list, is now mapped to its value. Likewise, $category_tobe_included is mapped to a list of included categories.

Each Joomla article belongs to a category, even if that category is uncategorized. This property allows a Joomla developer to decide which articles are to be affected by a plugin. The administration control panel allows a user to select multiple categories from the category field. When plg_content_creativecommons handles onContentPrepare, we would like it to return true, without modifying the article, upon call.

Let's consider how a Creative Commons license should look. First we want to generate a description that will be presented to a client that will look something like "Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License". Then we will want to generate a code that creativecommons.org will use to find the license description and accompanying image, e.g. "by-nc-sa". This is done by gathering license information provided by $params.

Next, we want to gather some information about the article, such as author name and URL.

We now have enough information to construct an HTML string to append to the article.

Now, all we have to do is get a reference to the article text and then append the license to it.

Viola, you now have an implementation of Creative Commons to present in articles, just like the one below.

Creating A Simple Joomla! Plugin by Jesse Riggs is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
Based on a work at jesse-riggs.com.