The code used in this article can be downloaded from here.

Plugin composition and operation

   

Like a module, in its simplest form, a plugin can consist of only two files, a PHP file with the actual code for the plugin, and an XML manifest that tells Joomla! what to do with the plugin.

Despite this apparent simplicity, plugins are very powerful, and more difficult to understand than modules and components.

Plugins are designed to run at certain times during the execution of our site, and they perform actions that can only be done at these times.

For example, in our sample site we want to hide some of our content from guests, and only show it to paid subscribers. This action can only be performed when we are actually preparing the content to be displayed, because we need to wait until we identify if the viewer is a guest or subscriber, and then make the changes to the content dynamically.

In a different example, checking if a subscriber’s subscription is valid is something that only needs to be done when they try to login, and not on every page load.

Plugin types

Plugins are divided into eight types, as follows:

• Authentication
• Content
• Editors
• Editors-XTD
• Search
• System
• User
• XML-RPC

Authentication

Authentication plugins are designed to allow the site to check the user’s authentication against a variety of sources.

The default is to check the user’s authentication against a username and password stored in the Joomla! database, which, as of Joomla! 1.5, will be the username and password fields in the #__user table (#__ is the table prefix we chose when setting up Joomla!). However, any source with a public API can be used to verify someone’s authentication details.

Common uses are LDAP, OpenID, a Google account, a subscription, community component, and more.

On our site, for example, we are already using an authentication plugin to verify the subscriptions of users when they attempt to login.

Content

Possibly the most commonly used of all plugins, content plugins allow content items to be modified or have additional features added to them.

We could, for example, use content plugins to cloak email addresses, embed audio or video into our pages, or do text replacements. We can even embed components and modules into our pages via plugins.

We will later look at a content plugin that we will use to hide and show content depending on a user’s subscription.

Editors

Editors plugins add WYSIWYG editors that we can use when editing our content.

We installed JCE on our site earlier, which is the most popular Joomla! editor plugin as of this publication according to Joomla.org.

Editors-XTD

Editors-XTD (extended) plugins allow us to add additional buttons to the editors. The Image, Read more, and Pagebreak buttons on the default Joomla! WYSIWYG editor, for example, are actually plugins.

Search

Search plugins allow us to search through the data from different components.

By default, Joomla! comes with plugins that search through content articles and the Contacts and Weblinks components. These can be expanded upon by creating or installing search plugins for other extensions.

System

System plugins are arguably the most powerful and most flexible types of plugins for Joomla!, as they can execute at several different pre-defined points during the execution of a Joomla! page plugin.

They can be used to perform a vast array of functions, such as loading extra scripts or CSS into the header of a web page, redirecting people away from pages, logging statistics, and more.

User

User plugins allow us to perform actions at different times with respect to users. Such times include logging in and out, and also when saving changes to a user’s profile. User plugins are often used to create a “bridge” between Joomla! and other web applications (such as the phpBB forum or the osCommerce e-commerce platform.).

XML-RPC

XML-RPC plugins are for communicating between our Joomla! site and other external applications, such as a desktop application or a different web site.

Plugin events

As a Joomla! site loads a page, it steps through a series of events as part of that process. The events it steps through are determined by the type of page it is loading. Plugins are always tied to one or more of these events, and are executed during those events as required.

When loading a page of content, for example, we would step through a mix of the system and some of the content events. When loading the same page for editing, we will step through the system events, different content events, and also possibly editor events.

The events triggered in Joomla! are:

Authentication

• onAuthenticate

Content

• onPrepareContent
• onAfterDisplayTitle
• onBeforeDisplayContent
• onBeforeContentSave
• onAfterContentSave

Editors

• onInit
• onGetContent
• onSetContent
• onSave
• onDisplay
• onGetInsertMethod

Editors XTD (Extended)

• onDisplay

Search

• onSearch
• onSearchAreas

System

• onAfterInitialise
• onAfterRoute
• onAfterDispatch
• onAfterRender

User

• onLoginUsexr
• onLoginFailure
• onLogoutUser
• onLogoutFailure
• onBeforeStoreUser
• onAfterStoreUser
• onBeforeDeleteUser
• onAfterDeleteUser

XML-RPC

• onGetWebServices

Most of these events are easy to understand from their name, but just in case, more information can be found on the Joomla! documentation wiki at http://docs.joomla.org/CategoryPlugins.

Some events are only activated at specific times, such as onAuthenticate, which is only activated when someone logs into their account. Others are activated on every page load. Content events are activated on all content pages and only on content pages, not on pages with components other than com_content.

Content plugins are also only executed on the main body content itself and don’t have access to the template or other module data. So a text replacement content plugin, for example, wouldn’t change any text in modules or the template, only in the main content itself.

It is actually possible for modules and components to manually activate plugin events with clever programming, but this is not the default Joomla! behavior. It is usually done when a developer wants to apply content plugin restrictions/changes to a module.

Plugin order

Aside from the events and types, there is a third important factor to consider when setting up our plugins. That is the order in which the plugins of a particular type are executed. This order is best observed on the Plugin Manager screen that can be found under the Extensions menu.

The order in which the plugins execute is something not many people think about, but is really quite powerful and useful. This is because the plugins which execute later, can then use the output or effects of the earlier executing plugins as input.

For example, imagine we have a plugin that displays different text for different user types, and we have another plugin that reads certain text values and replaces them with embedded video or audio. If we wanted to be able to show different videos to different groups, then we could use the first plugin to generate the different command strings for the second plugin, and have it generate them based on the user type.

The second plugin, our media embedding plugin, doesn’t even know that the first plugin exists. All it knows is which videos it needs to display based on what is in the content item.

If the media plugin executes first, then it will generate both videos regardless of the user type.

As another example, imagine we have some sort of external application and we log users into it after they authenticate via an authentication plugin. We need to make sure that this plugin is executed after all of our other authentication plugins that may check a user’s credentials or account status. Otherwise, someone may get logged into our external application even though they were prevented from login into our Joomla! site. So a hacker, for example, could get access to our external application without needing to even successfully get into our main site. This was all because we had the order of our plugins wrong.

So when we install and activate plugins, it is well worth taking the time to double check that everything happens in the order it is meant to be in. If one of our plugins is not behaving how it should, it might be worth checking the order to see if another plugin is conflicting with it.

Customizing a Plugin

Now that we have a better understanding of how our plugins work and fit together, we are going to try our hand at customizing one for our site. This will hopefully give us the understanding and confidence to make any other customizations we need in the future.

As with modules, it is often easier to find a plugin that does most of what we want it to do and then make changes to it so that it meets our needs more completely.

Looking back over our goals, one that requires a plugin is that we want to limit access to certain parts of our content to only our paying subscribers. This effect is going to be best achieved via content plugin, so we chose the Ninja Access plugin to fill this need.

To use Ninja Access we first need to mark the content we want to restrict with special tags and indicate the user groups we want to see what is contained within the tags. When the page is produced, the plugin reads the visitor’s user group and then compares it to the ones in the list provided by the tag.

If the user groups match, then the content is displayed, if not, then it is hidden.

For example:

{njaccess 0}shows only to guest users{/njaccess}
{njaccess 18,19,20,21,23,24,25}shows to all users who are not a guest{/njaccess}

The numbers in the examples above indicate the default Joomla! user group ids.

The most important ones are:

• 0 = Guests
• 18 = Registered
• 24 = Administrators
• 25 = Super Administrators

We could use this as it is, but as we don’t have a component installed to create new access groups, it won’t be very flexible. We could get into trouble in the future if we decide to let people register without getting a subscription, or create a free subscription. In this instance, we will have paying and free subscribers all in the number 18 user group.

Also, as we are always going to be restricting the same groups, we don’t really need to type the parameters in every single time. Making our plugins always restrict the same groups automatically will save us some time and reduce mistakes.

Lastly, do we really need to type njaccess every time? Let’s shorten it to something like soc—subscriber only content.

For our first dilemma, a better idea than groups might be to associate the access to certain AEC subscriptions that are currently active. That way if people’s subscriptions expire, or they get a free account, the content is still properly controlled regardless of their user groups.