Chapter 21: Customizing Joomla! Functionality 569 in the automatic creation of the sub-directory /tmpl. Declaring the mod_modulename.xml file is also not necessary. Note In the example list of files, I have included the index.html documents that you would want to create to pro- tect direct access to the directories. Don’t forget to create and include these. Simply copy an existing one from the Joomla! core for use in your module. After this change is made to the XML file all you need to do is zip up the files and name the archive something descriptive, preferable mod_modulename_version.zip. Note Although I have used the .zip format for this example, you can use your preferred archive format: .zip, .gz, .tar, .tar.gz. Caution Make sure that you are careful about what you zip up into the archive. Do not accidentally include system files generated by your local machine. This an easy mistake to make and it can sometimes cause problems for mod- ule installation. Working with Plugins Joomla! plugins are helper applications that work by detecting and responding to events. Technically they are observer classes that look to a global event dispatcher. The result is that you, as a developer, are able to create a plugin that executes some bit of code when an event occurs. This is most useful to you as a way to supplement your work on a component or module. Note For discussion of how to use a plugin with another extension, see http://docs.joomla.org/Tutorial:Using_plugins_in_your_own_extension . Plugin architecture Joomla 1.5 added the observer class JPlugin, and plugins follow the Observer design pattern. When you create a plugin, you extend the observer class JPlugin to observe Joomla’s observable class, the JEventDispatcher object. Put another way, creating a plugin is a two-part process whereby you create a class to extend JPlugin, and then write a method for each event you want the plugin to handle. Part IV: Customizing and Extending the System 570 Note Joomla! includes a variety of core events. For a complete list, organized into groups and listed alphabetically, see http://docs.joomla.org/Tutorial:Plugins . Creating a new plugin The system includes a number of plugins, all organized into eight categories and kept in the direc- tory /plugins. Plugins require, at a minimum, two files: pluginname.php and pluginname. xml . The PHP contains the primary code, while the XML contains the descriptive information needed for the plugin to be recognized and used by Joomla! Given that most plugins are relatively small and narrowly-tailored units of code, it is unlikely you will be modifying existing plugins. If you want to make changes, simply create a new plugin and add it to the system. Your first step will be to determine how you will classify the plugin. The default classifications in Joomla! 1.5.x are: l Authentication l Content l Editors l Editors-xtd l Search l System l User l xmlrpc Pick the classification that best fits your new plugin, as your plugin files will go into that directory inside the /plugins folder on the server. Note If you want to step outside the default plugin classification schema you can create your own classification by adding another subdirectory inside the /plugins directory. The structure of the plugin files is best shown by looking at examples. Joomla! makes this easy. Inside each of the plugin directories in the Joomla! core, you will find example files that can serve as a template to help jumpstart your work creating new plugins. Inside the /plugins/content directory you can find example.php and example.xml. The essence of that PHP file, without the comment lines, is as follows: jimport( ‘joomla.plugin.plugin’ ); class plgContentExample extends JPlugin Chapter 21: Customizing Joomla! Functionality 571 { function plgContentExample( &$subject, $params ) { parent::__construct( $subject, $params ); } function onPrepareContent( &$article, &$params, $limitstart ) { global $mainframe; } function onAfterDisplayTitle( &$article, &$params, $limitstart ) { global $mainframe; return ‘’; } function onBeforeDisplayContent( &$article, &$params, $limitstart ) { global $mainframe; return ‘’; } function onAfterDisplayContent( &$article, &$params, $limitstart ) { global $mainframe; return ‘’; } function onBeforeContentSave( &$article, $isNew ) { global $mainframe; return true; } function onAfterContentSave( &$article, $isNew ) { global $mainframe; return true; } } Look at what happens in the code: l The first line uses the jimport function to import Joomla’s general plugin library, JPlugin. l The second line sets out the class plgContentExample as an extension of JPlugin. Note the naming convention here as it is mandatory: plgNameofdirectoryNameofplugin. l What follows afterwards are seven methods, each tied to a specific event. Note the naming convention: The name of the method is the same as the event that triggers it. Part IV: Customizing and Extending the System 572 l The example plugin, above, does nothing. It is intended as a template for your use. You would add your plugin action code inside whichever method is appropriate, after the line global $mainframe; l For a breakdown of the various parameters listed in the preceding code, see the discussion on creating a content plugin at http://docs.joomla.org/How_to_create_a_ content_plugin Note To learn more about when events are triggered, view the API Execution Order page at http://docs.joomla.org/API_Execution_Order . The XML file is even simpler. It is reproduced in its entirety: <?xml version=”1.0” encoding=”utf-8”?> <install version=”1.5” type=”plugin” group=”content”> <name>Content - Example</name> <author>Joomla! Project</author> <creationDate>July 2007</creationDate> <copyright>Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.</copyright> <license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</ license> <authorEmail>admin@joomla.org</authorEmail> <authorUrl>www.joomla.org</authorUrl> <version>1.0</version> <description>An example content plugin</description> <files> <filename plugin=”example”>example.php</filename> </files> <params/> </install> This file’s key function is to provide the information necessary for installation of the plugin, though it can also be used to activate parameters that can be set by the administrator from inside the Plugin Manager. Key points to note about the contents of this file: The <install> tag declared at the outset tells the system the type of file that is being installed, in this case a plugin, and the group to which it belongs, in this case, content. Caution Make sure your XML file is created in UTF-8 format. Tip The official Joomla! documentation sites contain three good, clear tutorials on creating plugins: http://docs.joomla.org/How_to_create_a_content_plugin, http://docs.joomla.org/How_to_create_a_search_ plugin, and http://developer.joomla.org/tutorials/184-how-to-create-a-joomla-plugin.html. Chapter 21: Customizing Joomla! Functionality 573 Registering a plugin Registering your plugin in the database is a quick way to get it into the back end, so you can turn it on and off and work with the parameters during development. Note Registering your plugin is optional; you can achieve the same thing by setting up the installer information in the XML file and using the Joomla! Extension Installer to handle this automatically. However, because you are likely to be writing and revising your plugin, you may want to register it at the very beginning of the process, so you can see the impact of your changes and manipulate the plugin more easily during development. The process of registering a plugin involves simply entering a record for the plugin into the jos_plugins table in your site’s database. You can accomplish this process either by running an SQL query or by accessing phpMyAdmin and entering the information manually. To register a new plugin using phpMyAdmin, do the following: 1. Access phpMyAdmin on the server where your Joomla! installation is located. 2. Select the name of your database from the list on the left. The database information loads in the screen. 3. From the list of tables on the left side of the screen, select the option jos_plugins. The jos_plugins table summary information displays on the right side of the screen. 4. Click the Insert tab. The Insert dialogue loads. 5. Type the full name of your new plugin in the field marked title. Note that the stan- dard full name is section - plugin Name, e.g., Content - Email Cloaking. 6. In the field labeled element, type the machine-friendly name for the plugin. 7. In the field marked folder, enter the classification type for the plugin 8. Type the value 1 for the field published. 9. Click the button labeled Go. The system now creates a new row in the table containing your plugin information. After your plugin is registered, you can access it from the Joomla! admin system where you can view your work in progress. Packaging a plugin Proper packaging may not be an issue if your plugin is only intended for your own use, but if you intend to give your plugin to others, or you want to install it again elsewhere, you should go ahead and create a proper installation package for the plugin. Proper packaging allows you to manage plugin installation through Joomla’s default Extension Installer. Packages are archives that contain all the necessary elements of a plugin, along with an XML file containing the information needed by the Joomla! installer. The XML file must be modified to include a list of all the files that need to be installed. Because you already have an XML file for your plugin, you can simply add in the declarations needed by the Installer. Each file is listed inside the element <filename>. All filename elements are wrapped by the tag <files>. Part IV: Customizing and Extending the System 574 Looking at an example makes this simpler. Looking at the example.xml file listed earlier in this section, you will note the following lines of code: <files> <filename plugin=”example”>example.php</filename> </files> Note that it is not necessary to list the directory for the plugin files because the system automati- cally places the plugin in the proper directory according to its group attribute in the installer tag. Declaring the example.xml file is also not necessary. After this change is made to the XML file, all you need to do is zip up the files and name the archive something descriptive, preferable plg_pluginname-version.zip. Note Although this example uses the .zip archive format, you can use your preferred archive format: .zip, .gz, .tar, .tar.gz. Caution Make sure that you are careful about what you zip up into the archive. Do not accidentally include system files generated by your local machine. This is an easy mistake to make, and it can sometimes cause problems for plugin installation. Summary In this chapter, we have covered the basics of customizing the functionality of the Joomla! system. You learned the following: l Useful tools for working with Joomla! code l The elements of component architecture l How to modify components l The elements of a typical module l How to modify modules l How to create new modules l The elements of plugins l How to create new plugins . find example.php and example.xml. The essence of that PHP file, without the comment lines, is as follows: jimport( joomla. plugin.plugin’ ); class plgContentExample extends JPlugin Chapter 21: . plugins: http://docs .joomla. org/How_to_create_a_content_plugin, http://docs .joomla. org/How_to_create_a_search_ plugin, and http://developer .joomla. org/tutorials /18 4-how-to-create-a -joomla- plugin.html. Chapter 21: Customizing Joomla! Functionality 573 Registering. discussion of how to use a plugin with another extension, see http://docs .joomla. org/Tutorial:Using_plugins_in_your_own_extension . Plugin architecture Joomla 1. 5 added the observer class JPlugin, and