The Joomla! Community Magazine™

Introduction to Plugin Development for Site Builders

Written by | Thursday, 01 May 2014 00:00 | Published in 2014 May
Of all the Joomla Extension types available, plugins are the simplest to implement, but can be the most powerful with regards to customising your Joomla! website. Built into Joomla! are a number of events that trigger the execution of plugins, which essentially allow us to highjack the standard Joomla! code or output and insert our own code.

Imagine you are building a website for a client and they wish to run webinars for their customers. Now the date and time of these webinars is going to vary depending on the timezone of the viewer, so ideally we would want to show the user the local date and time.

As a site builder, your first step would probably be to search the JED for a suitable existing extension for this purpose, which no doubt one probably exists, but what if the existing solutions are overkill and you just want something simple? Or what if there is nothing available for the problem you are trying to solve?

This is a scenario where you might consider creating your own content plugin. This can be done with a few lines of code, and you don’t need to be a programming geek to be able to create this.

Your first step is to create a folder called plg_content_tzconvertor, and in this create the installation XML file for your plugin tzconvertor.xml. This file tells Joomla! all about your plugin, what files it includes, what type of plugin this is, and who created it.

Note: If you are planning on sharing this plugin with others, then it’s a good idea to check the JED first to make sure that the name you have selected is unique.

<?xml version="1.0" encoding="UTF-8"?>
<extension  
      version="3.0" 
      type="plugin"
      method="upgrade" 
      group="content">
   <name>Content – Timezone Convertor</name>
   <author>Tim Plummer</author>
   <creationdate>April 2014</creationdate>
   <copyright>Copyright (C) 2014 Your Company. All rights reserved.</copyright>
   <license> http://www.gnu.org/licenses/gpl-3.0.html</license>
   <authoremail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authoremail>
   <authorurl>http://www.yourcompany.com</authorurl>
   <version>1.0.0</version>
   <description>This plugin will replace date and time with the local equivalent based on user’s timezone.
Don't forget to publish this plugin!
   </description>
   <files>
      <filename plugin="tzconvertor">tzconvertor.php</filename>
      <filename>index.html</filename>
   </files>
</extension>

The plugin group content tells Joomla! what type of plugin this will be and determines which event triggers we can use.

Now we need to create the PHP file for our plugin. In your plg_content_tzconvertor folder, create the file tzconvertor.php.

<?php
defined('_JEXEC') or die;
jimport('joomla.plugin.plugin');
class plgContentTzconvertor extends JPlugin
{
   function plgContentTzconvertor( &$subject, $params )
   {
      parent::__construct( $subject, $params );
   }
   public function onContentPrepare($context, &$row, &$params, $page = 0)
   {
      // Do not run this plugin when the content is being indexed
      if ($context == 'com_finder.indexer')
      {
         return true;
      }
      if (is_object($row))
      {
         return $this->Tzconvertor($row->text, $params);
      }
         return $this-> Tzconvertor ($row, $params);
      }
   protected function Tzconvertor (&$text, &$params)
   {
      $user = JFactory::getUser();
      $timeZone = $user->getParam('timezone');
      // matches date and time in format yyyy-mm-dd hh:mm
      $pattern = '/(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2})/';
      $found = preg_match_all($pattern, $text, $matches);
      if ( $found )
      {
         foreach ( $matches[0] as $value )
         {
            $replacement=JHtml::date(strtotime($value) , 'Y-m-d g:i a', true);
            if($timeZone)
            {
               $replacement .= ' ('.$timeZone.')';
            }
            $text = preg_replace($pattern, $replacement, $text);
         }
      }
      return true;
   }
}

The onContentPrepare is the event that we are targeting for this plugin, and this is executed when we display article content on the site. This calls the Tzconvertor function which is where we put all our custom code that does all the hard work. First, we get the details of the current user that is logged in, and we look up what their timezone is set to.

Then we search through the text of the article, and see if any of it matches our regex pattern which is looking for a date time in the format yyyy-mm-dd hh:mm. If we find a match, we replace the date time with an adjusted version that has factored in the timezone preference of the user. We also display the name of the timezone, just to make it clear to the user what timezone this date time is for.

Note the true flag in the JHtml:date function which indicates to use the user’s timezone setting, rather than a value of false which would use system settings for timezone.

Now in your plg_content_tzconvertor folder, create the file index.html, which will present the user with a blank page if they try to browse the folder directly, instead of potentially exposing information about your website to malicious users.

<html><body bgcolor="#FFFFFF"></body></html>

All you need to do now is zip it up, and install it on your site.

When this plugin is enabled, for logged in users it will find any date time in the format yyyy-mm-dd hh:mm in an article and adjust to the local timezone of the user.

image001

Note that the date and time entered in the article should be in UTC timezone

When a user with Sydney timezone set logs in, they will see the adjusted date time.

 image002

So as you can see, effectively we have added 17 lines of custom code to a standard Joomla! content plugin, which I think every site builder would be capable of doing. Now that you can see how simple plugins can be, why not give it a go next time your client gives you an unusual requirement.

Read 8098 times
Tagged under Developers, English
Tim Plummer

Tim Plummer

Tim Plummer is a self-confessed Joomla! addict from the land down under (Australia). He runs the Sydney Joomla! User Group, and is coordinator of the annual Joomla!Day Sydney conference. Tim has a day job in IT for a multinational manufacturer, and in his spare time develops Joomla extensions (when his kids let him). Tim is also the author of Learning Joomla! 3 Extension Development published by Packt Publishing in July 2013.