J1.5:Creating a content plugin

The "J1.5" namespace is an archived namespace. This page contains information for a Joomla! version which is no longer supported. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

This Page Needs Your Help

Description

There are lots of abilities of the use of a Content Plugin. They all have to do with the display of your content and so your articles. You will need at least two files for this Plugin. An XML file and a PHP file. Because there are so many differences between two Content Plugins in the PHP file, two examples of them will be explained in this document. Also a part about internationalization (with INI files) is added. And last but not least: the Joomla! Core Content Plugin coding examples and the quick tips.

XML file

The XML file is named the same as the PHP file, and is one of the two required files. Always start off with the XML tag and define that it is written in a UTF-8 format.

<?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE install PUBLIC 
  "-//Joomla! 1.5//DTD plugin 1.0//EN" "http://dev.joomla.org/xml/1.5/plugin-install.dtd">

To define that the plugin has to be a content plugin, add this line:

<install version="1.5" type="plugin" group="content">

The type will define it is a Plugin, the group defines the Plugin is in the group of Content Plugins.

After that, add some information about yourself and the Plugin, like this:

<name>Name of your Content Plugin</name>
<creationDate>Created Date</creationDate>
<author>Your name</author>
<authorEmail>Your e-mail address</authorEmail>
<authorUrl>Your website</authorUrl>
<copyright>Copyright</copyright>
<license>License, for example GNU/GPL</license>
<version>Version of the plugin</version>
<description>Description of the Plugin; showed with installation and when editing 
the Plugin in the Plugin Manager</description>

And now include your PHP file to the Content Plugin. The name of this file should be the same as the name of this XML file. Put this name also behind the plugin="" part.

You could also add more files for your plugin, for example an image. Just add another row between <files> and </file>, and then place the file between <filename> tags.

<files>
   <filename plugin="nameofplugin">nameofplugin.php</filename>
</files>

For the internationalization, we will use language files. This is not required, but people from other countries will love it they can easily translate your plugin to their own language. The language tags can be found here: [1] (use the ISO 639-1 column) and here: [2]

<languages>
   <language tag="en-GB">language/en-GB/en-GB.plg_content_nameofplugin.INI</language>
</languages>

Optionally, you could add some parameters to the Plugin. These will look like this:

<params>
   <param name="paramname" type="typeofparameter" default="defaultsetting" label="title" description="description"/>
</params>

• Param name: The name of the parameter. You will need this when creating the PHP file.
• Param type: You could choose between several types of parameters. Look at this document to learn something about the different types: [3]
• Param default: The default setting for this parameter.
• Param label: The name of this parameter displayed in the edit screen of this Plugin in the Plugin Manager.
• Param description: The text which appears as a tool tip for this parameter.

When you do not want to use parameters, add the following tag:

<params/>

And do not forget to end your XML file with the following tag:

</install>

PHP file - Example 1

Example 1 is about the Content Plugin vote. The PHP file will be displayed here, with comments what every function or part does.

<?php

//First start with some information about the Content Plugin, its author and probably some other information
/**
* @version		$Id: vote.php 9764 2007-12-30 07:48:11Z ircmaxell $
* @package		Joomla
* @copyright	Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license		GNU/GPL, see LICENSE.php
* Joomla! is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*/

//You can not directly access the file when you put this code at the beginning:
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

//Now set the registerEvent. The action will start before the content is opened.
//In plgContentVote you should replace Vote by the name of your own Plugin.
$mainframe->registerEvent( 'onBeforeDisplayContent', 'plgContentVote' );

//Here the real function starts.
function plgContentVote( &$row, &$params, $page=0 )
{

//Set the JURI
	$uri = & JFactory::getURI();

	$id 	= $row->id;

//$html is made empty
	$html 	= '';

//Get the rating_count and the parameters from the XML file
	if (isset($row->rating_count) && $params->get( 'show_vote' ) && !$params->get( 'popup' ))
	{

//Load the language file
		JPlugin::loadLanguage( 'plg_content_vote' );

//Add the general HTML output
		$html .= '<form method="post" action="' . $uri->toString( ) . '">';
		$img = '';

//Look for images in template if available
		$starImageOn 	= JHTML::_('image.site',  'rating_star.png', '/images/M_images/' );
		$starImageOff 	= JHTML::_('image.site',  'rating_star_blank.png', '/images/M_images/' );

//Show the 'full' star images when the rate number is higher then 0
		for ($i=0; $i < $row->rating; $i++) {
			$img .= $starImageOn;
		}

//Show the the 'empty' star images when the rate number is less then 5
		for ($i=$row->rating; $i < 5; $i++) {
			$img .= $starImageOff;
		}

//HTML output
		$html .= '<span class="content_rating">';
		$html .= JText::_( 'User Rating' ) .':'. $img .'&nbsp;/&nbsp;';
		$html .= intval( $row->rating_count );
		$html .= "</span>\n<br />\n";

//Get params
		if (!$params->get( 'intro_only' ))
		{

//HTML output; set the display of the images
			$html .= '<span class="content_vote">';
			$html .= JText::_( 'Poor' );
			$html .= '<input type="radio" alt="vote 1 star" name="user_rating" value="1" />';
			$html .= '<input type="radio" alt="vote 2 star" name="user_rating" value="2" />';
			$html .= '<input type="radio" alt="vote 3 star" name="user_rating" value="3" />';
			$html .= '<input type="radio" alt="vote 4 star" name="user_rating" value="4" />';
			$html .= '<input type="radio" alt="vote 5 star" name="user_rating" value="5" checked="checked" />';
			$html .= JText::_( 'Best' );
			$html .= '&nbsp;<input class="button" type="submit" name="submit_vote" value="'. JText::_( 'Rate' ) .'" />';
			$html .= '<input type="hidden" name="task" value="vote" />';
			$html .= '<input type="hidden" name="option" value="com_content" />';
			$html .= '<input type="hidden" name="cid" value="'. $id .'" />';
			$html .= '<input type="hidden" name="url" value="'.  $uri->toString( ) .'" />';
			$html .= '</span>';
		}
//HTML output; close the <form> tag
		$html .= '</form>';
	}
//Return HTML output
	return $html;
}

PHP file - Example 2

Example 2 is about the Content Plugin load module. It is a plugin made for displaying modules within the articles. The PHP file will be displayed here, with comments what every function or part does.

<?php
//First start with some information about the Content Plugin, its author and probably some other information
/**
* @version		$Id: loadmodule.php 9764 2007-12-30 07:48:11Z ircmaxell $
* @package		Joomla
* @copyright	Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license		GNU/GPL, see LICENSE.php
* Joomla! is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*/
//You can not directly access the file when you put this code at the beginning:
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

//Now set the registerEvent. The action will start before the content is opened.
//In plgContentVote you should replace Vote by the name of your own Plugin.
$mainframe->registerEvent( 'onPrepareContent', 'plgContentLoadModule' );

//The real function starts here
function plgContentLoadModule( &$row, &$params, $page=0 )
{
//Access the database
	$db =& JFactory::getDBO();
//Check whether the bot should process or not
	if ( JString::strpos( $row->text, 'loadposition' ) === false ) {
		return true;
	}

//Get plugin info
	$plugin =& JPluginHelper::getPlugin('content', 'loadmodule');

//Search for this tag in the content
 	$regex = '/{loadposition\s*.*?}/i';

//Access the parameters
 	$pluginParams = new JParameter( $plugin->params );

//Check whether plugin has been unpublished
	if ( !$pluginParams->get( 'enabled', 1 ) ) {
		$row->text = preg_replace( $regex, '', $row->text );
		return true;
	}

//Find all instances of plugin and put in $matches
	preg_match_all( $regex, $row->text, $matches );

//Number of plugins
 	$count = count( $matches[0] );

//Plugin only processes if there are any instances of the plugin in the text
 	if ( $count ) {
//Get plugin parameters
	 	$style	= $pluginParams->def( 'style', -2 );

 		plgContentProcessPositions( $row, $matches, $count, $regex, $style );
	}
}
//Function to process the posistions in the content
function plgContentProcessPositions ( &$row, &$matches, $count, $regex, $style )
{
 	for ( $i=0; $i < $count; $i++ )
	{

//Get the correct output for $load
 		$load = str_replace( 'loadposition', '', $matches[0][$i] );
 		$load = str_replace( '{', '', $load );
 		$load = str_replace( '}', '', $load );
 		$load = trim( $load );

//Load position
		$modules	= plgContentLoadPosition( $load, $style );
		$row->text 	= preg_replace( '{'. $matches[0][$i] .'}', $modules, $row->text );
 	}

//Remove tags without matching module positions
	$row->text = preg_replace( $regex, '', $row->text );
}

//Function to load the module in the content
function plgContentLoadPosition( $position, $style=-2 )
{

//Get document
	$document	= &JFactory::getDocument();

//Load module
	$renderer	= $document->loadRenderer('module');

//Load the parameter
	$params		= array('style'=>$style);

	$contents = '';

	foreach (JModuleHelper::getModules($position) as $mod)  {
		$contents .= $renderer->render($mod, $params);
	}

//Return content with loaded modules
	return $contents;
}

INI file(s)

For internationalization it is good to use the INI files. You can add to the language file everyting which outputs text to the user, in this order:

• XML description tag
• XML label and description attributes from parameters
• JText::_( 'string' ) used by the plugin

Start your INI file with something like this:

# $Id: en-GB.plg_content_nameofplugin.ini
# Joomla! Project
# Copyright (C) 2005 - 2007 Open Source Matters. All rights reserved.
# License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
# Note : All ini files need to be saved as UTF-8 - No BOM

Of course, you could also add other information, like the author.

For example, this parameter:

<param name="mode" type="list" default="1" label="Mode" description="Select how the emails will be displayed">
   <option value="0">Nonlinkable Text</option>
   <option value="1">As linkable mailto address</option>
</param>

Will cause the following in the INI file:

MODE=Mode
SELECT HOW THE EMAILS WILL BE DISPLAYED=Select how the e-mails will be displayed
NONLINKABLE TEXT=Nonlinkable text
AS LINKABLE MAILTO ADDRESS=As linkable mailto address

The file looks repetitive, but will be very useful for translaters.

When you want to make your Content Plugin available in more languages, first add them to the <languages> tag in the XML file. Then create the same INI file, and change the part after the =, for example the dutch version would be:

MODE=Modus
SELECT HOW THE EMAILS WILL BE DISPLAYED=Selecteer hoe de e-mails worden weergegeven
NONLINKABLE TEXT=Niet-linkbare tekst
AS LINKABLE MAILTO ADDRESS=Als een linkbaar mailto adres

Coding examples

There are seven Joomla! Core Content Plugins. To look at them, you can learn a lot. You can see them 'working' when you go to the Back-end of your Joomla! 1.5 installation, then go to the menu 'Extensions' and select the 'Plugin Manager'. Click on the name of the Plugin to edit it; and see it working. Also watch the content and see what happens when you insert a pagebreak for example.

• Plugin Content - Emailcloak
  • \plugins\content\emailcloak.XML
  • \plugins\congent\emailcloak.PHP
• Plugin Content - Example
  • \plugins\content\example.XML
  • \plugins\congent\example.PHP
• Plugin Content - Geshi
  • \plugins\content\geshi.XML
  • \plugins\congent\geshi.PHP
• Plugin Content - Load Module
  • \plugins\content\loadmodule.XML
  • \plugins\congent\loadmodule.PHP
• Plugin Content - Pagebreak
  • \plugins\content\pagebreak.XML
  • \plugins\congent\pagebreak.PHP
• Plugin Content - Page navigation
  • \plugins\content\pagenavigation.XML
  • \plugins\congent\pagenavigation.PHP
• Plugin Content - Vote
  • \plugins\content\vote.XML
  • \plugins\congent\vote.PHP
  • \language\en-GB\en-GB.plg_content_vote.INI

Quick tips

• In the PHP file you often forget to place an semicolon (;) at the end of a row, which causes errors. Check this before you test your Plugin and you will eliminate many errors.
• Take care of the fact that the parameters in the XML file are closed correctly. When you add options for example, you need to close it with </param>.
• It is easy to test on a localhost when you are still busy with editing your Plugin.
• When making a zip-file to test it, do not forget to make the directories for the language files. A typical zip will contain the following:
  • nameofplugin.XML
  • nameofplugin.PHP
  • language\en-GB\en-GB.plg_content_nameofplugin.INI