Joomla! Documentation - User contributions [en]

J1.5:Creating a content plugin

2010-04-09T17:04:10Z

Dynedain: /* XML file */ updating DTD

[[Category:Development]]
[[Category:Plugins]]
==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.
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install
PUBLIC "-//Joomla! 1.5//DTD plugin 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/plugin-install.dtd">
To define that the plugin has to be a content plugin, add this line:
<source lang="xml"><install version="1.5" type="plugin" group="content"></source>
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:
<source lang="xml">
<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></source>
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 </files>, and then place the file between <filename> tags.
<source lang="xml">
<files>
<filename plugin="nameofplugin">nameofplugin.php</filename>
</files></source>

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. Plugin language files are always installed in administrator/languages/xx-XX/ where xx-XX is the code for a language already installed in Joomla.
The language tags can be found here: [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes] (use the ISO 639-1 column) and here: [http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements]
<source lang="xml">
<languages>
<language tag="en-GB">en-GB.plg_content_nameofplugin.ini</language>
</languages></source>
Optionally, you could add some parameters to the Plugin. These will look like this:
<source lang="xml">
<params>
<param name="paramname" type="typeofparameter" default="defaultsetting" label="title" description="description"/>
</params></source>
*'''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: [http://docs.joomla.org/Using_the_core_parameter_types]
*'''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:
<source lang="xml"><params/></source>

And do not forget to end your XML file with the following tag:
<source lang="xml"></install></source>

==PHP file==
Start your PHP file with the general licensing and author information about your content plugin.

<source lang="PHP"><?php
/**
* @version $Id: nameofplugin.php revision date lasteditedby $
* @package Joomla
* @subpackage Content
* @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.
*/ </source>

Next, always put the following code in any PHP file:
<source lang="PHP">
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );</source>
This prevents people from directly accessing this PHP file.

After that, you should import the general plugin file of Joomla!'s library
<source lang="PHP">jimport( 'joomla.plugin.plugin' );</source>

To indicate that you're writing a Content plugin, add the following code.
<source lang="PHP">class plgContentNameofplugin extends JPlugin {</source>
Please note the use of capital letters. You should replace Nameofplugin by the name of your own plugin.

Now, it's time to construct the plugin:
<source lang="PHP">/**
* Constructor
*
* For php4 compatability we must not use the __constructor as a constructor for plugins
* because func_get_args ( void ) returns a copy of all passed arguments NOT references.
* This causes problems with cross-referencing necessary for the observer design pattern.
*
* @param object $subject The object to observe
* @param object $params The object that holds the plugin parameters
* @since 1.5
*/
function plgContentNameofplugin( &$subject, $params )
{
parent::__construct( $subject, $params );
}</source>

You should choose now at which moment the plugin should be rendered. You can choose from the following:

* onBeforeContentSave : This is an event that is called right before the content is saved into the database.
* onAfterContentSave : This is an event that is called after the content is saved into the database.
* onPrepareContent : This is the first stage in preparing content for output and is the most common point for content orientated plugins to do their work.
* onAfterDisplayTitle : This is a request for information that should be placed between the content title and the content body.
* onBeforeDisplayContent : This is a request for information that should be placed immediately before the generated content.
* onAfterDisplayContent : This is a request for information that should be placed immediately after the generated content.

More information on which type you should use for your plugin, including several examples, can be found here: [[Reference:Content_Events_for_Plugin_System]]

===onBeforeContentSave===
Use the following code:
<source lang="PHP"> function onBeforeContentSave( &$article, $isNew )
{
global $mainframe;
//add your plugin codes here
return true;
}</source>
The parameters article and isNew should contain the following:
* article : A reference to the JTableContent object that is being saved which holds the article data.
* isNew : A boolean which is set to true if the content is about to be created.

===onAfterContentSave===
Use the following code:
<source lang="PHP"> function onAfterContentSave( &$article, $isNew )
{
global $mainframe;
//add your plugin codes here
return true;
}</source>
The parameters article and isNew should contain the following:
* article : A reference to the JTableContent object that was saved which holds the article data.
* isNew : A boolean which is set to true if the content was created.

===onPrepareContent===
Use the following code:
<source lang="PHP"> function onPrepareContent( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
//no return value
}</source>
The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===onAfterDisplayTitle===
Use the following code:
<source lang="PHP"> function onAfterDisplayTitle( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}</source>
The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===onBeforeDisplayContent===
Use the following code:
<source lang="PHP"> function onBeforeDisplayContent( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}</source>

The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===onAfterDisplayContent===
Use the following code:
<source lang="PHP"> function onAfterDisplayContent( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}</source>

The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

==PHP file - Example==
This example PHP file is about the Content Plugin load module. It is a plugin made for displaying modules within the articles.
The commented PHP file used in this example is the file which will be included in Joomla! 1.6. This has been done because the content plugin files in Joomla! 1.5 are not refactored yet to the new standards.
<source lang="PHP">
<?php
// The general information at the top of each file
/**
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2009 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License, see LICENSE.php
*/

// No direct access allowed to this file
defined( '_JEXEC' ) or die( 'Restricted access' );

// Import Joomla! Plugin library file
jimport('joomla.plugin.plugin');

//The Content plugin Loadmodule
class plgContentLoadmodule extends JPlugin
{
/**
* Plugin that loads module positions within content
*/
// onPrepareContent, meaning the plugin is rendered at the first stage in preparing content for output
public function onPrepareContent( &$row, &$params, $page=0 )
{
// A database connection is created
$db = JFactory::getDBO();
// simple performance check to determine whether bot should process further
if ( JString::strpos( $row->text, 'loadposition' ) === false ) {
return true;
}

// expression to search for
$regex = '/{loadposition\s*.*?}/i';

// check whether plugin has been unpublished
if ( !$this->params->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 = $this->params->def( 'style', -2 );
$this->_process( $row, $matches, $count, $regex, $style );
}
// No return value
}
// The proccessing function
protected function _process( &$row, &$matches, $count, $regex, $style )
{
for ( $i=0; $i < $count; $i++ )
{
$load = str_replace( 'loadposition', '', $matches[0][$i] );
$load = str_replace( '{', '', $load );
$load = str_replace( '}', '', $load );
$load = trim( $load );

$modules = $this->_load( $load, $style );
$row->text = preg_replace( '{'. $matches[0][$i] .'}', $modules, $row->text );
}

// removes tags without matching module positions
$row->text = preg_replace( $regex, '', $row->text );
}
// The function who takes care for the 'completing' of the plugins' actions : loading the module(s)
protected function _load( $position, $style=-2 )
{
$document = &JFactory::getDocument();
$renderer = $document->loadRenderer('module');
$params = array('style'=>$style);

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

==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:
<source lang="INI"># $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</source>
Of course, you could also add other information, like the author.

For example, this parameter:
<source lang="XML">
<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></source>
Will cause the following in the INI file:
<source lang="INI">
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
</source>
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:
<source lang="INI">
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
</source>

==Coding examples==
There are seven Joomla! Core Content Plugins. These are all not yet refactored to the new standards. For learning how to write good plugins, its better to look at the (refactored) files of Joomla! 1.6.
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.

==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.
*A typical zip will contain the following:
**nameofplugin.XML
**nameofplugin.PHP
**en-GB.plg_content_nameofplugin.ini

J1.5:Creating a search plugin

2010-04-09T17:03:32Z

Dynedain: /* XML file */ updating DTD

{{review}}
[[Category:Development]]
[[Category:Plugins]]
==Description==
This document is about how to create a Search Plugin. You can use a Search Plugin to search through the database of your Joomla! site. To create a plugin, you will at least need two files; an XML file and a PHP file. For internationalization it is good to create an INI file as well.

==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.
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC
"-//Joomla! 1.5//DTD plugin 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/plugin-install.dtd">
To define that the plugin has to be a search plugin, add this line:
<source lang="xml"><install version="1.5" type="plugin" group="search"></source>
The type will define it is a plugin, the group defines the Plugin is in the group of search plugins.

After that, add some information about yourself and the plugin, like this:
<source lang="xml">
<name>Name of your search plugin</name>
<creationDate>Creation date</creationDate>
<author>Your name</author>
<authorEmail>Your e-mail address</authorEmail>
<authorUrl>Your website</authorUrl>
<copyright>Copyright information</copyright>
<license>License, for example GNU/GPL</license>
<version>Version of the plugin</version>
<description>Description of the plugin; showed during installation and when editing
the plugin in the Plugin Manager</description></source>
And now, include your PHP file to the Search 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.
<source lang="xml">
<files>
<filename plugin="nameofplugin">nameofplugin.php</filename>
</files></source>

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: [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes] (use the ISO 639-1 column) and here: [http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements]
<source lang="xml">
<languages>
<language tag="en-GB">language/en-GB/en-GB.plg_search_nameofplugin.ini</language>
</languages></source>
Optionally, you could add some parameters to the plugin. These will look like this:
<source lang="xml">
<params>
<param name="paramname" type="typeofparameter" default="defaultsetting" label="title" description="description"/>
</params></source>
*'''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: [http://docs.joomla.org/Using_the_core_parameter_types]
*'''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.

And do not forget to end your XML file with the following tag:
<source lang="xml"></install></source>

==PHP file==
The PHP file of your plugin is probably the most important file of the plugin. This is an example PHP file of a search plugin. The comments are included.

<source lang="PHP"><?php
//First start with information about the Plugin and yourself. For example:
/**
* @version $Id: nameofplugin.php versionnumber date author
* @copyright Copyright
* @license License, for example GNU/GPL
* All other information you would like to add
*/

//To prevent accessing the document directly, enter this code:
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

//Now define the registerEvent and the language file. Replace 'nameofplugin' with the name of your plugin.
$mainframe->registerEvent( 'onSearch', 'plgSearchnameofplugin' );
$mainframe->registerEvent( 'onSearchAreas', 'plgSearchnameofpluginAreas' );

JPlugin::loadLanguage( 'plg_search_nameofplugin' );

//Then define a function to return an array of search areas. Replace 'nameofplugin' with the name of your plugin.
function &plgSearchnameofpluginAreas()
{
static $areas = array(
'nameofplugin' => 'Nameofplugin'
);
return $areas;
}

//Then the real function has to be created. The database connection should be made.
//The function will be closed with an } at the end of the file.
function plgSearchnameofplugin( $text, $phrase='', $ordering='', $areas=null )
{
$db =& JFactory::getDBO();
$user =& JFactory::getUser();

//If the array is not correct, return it:
if (is_array( $areas )) {
if (!array_intersect( $areas, array_keys( plgSearchnameofpluginAreas() ) )) {
return array();
}
}

//It is time to define the parameters! First get the right plugin; 'search' (the group), 'nameofplugin'.
$plugin =& JPluginHelper::getPlugin('search', 'nameofplugin');

//Then load the parameters of the plugin..
$pluginParams = new JParameter( $plugin->params );

//And define the parameters. For example like this..
$limit = $pluginParams->def( 'nameofparameter', defaultsetting );

//Use the function trim to delete spaces in front of or at the back of the searching terms
$text = trim( $text );

//Return Array when nothing was filled in
if ($text == '') {
return array();
}

//After this, you have to add the database part. This will be the most difficult part, because this changes per situation.
//In the coding examples later on you will find some of the examples used by Joomla! 1.5 core Search Plugins.
//It will look something like this.
$wheres = array();
switch ($phrase) {

//search exact
case 'exact':
$text = $db->Quote( '%'.$db->getEscaped( $text, true ).'%', false );
$wheres2 = array();
$wheres2[] = 'LOWER(a.name) LIKE '.$text;
$where = '(' . implode( ') OR (', $wheres2 ) . ')';
break;

//search all or any
case 'all':
case 'any':

//set default
default:
$words = explode( ' ', $text );
$wheres = array();
foreach ($words as $word)
{
$word = $db->Quote( '%'.$db->getEscaped( $word, true ).'%', false );
$wheres2 = array();
$wheres2[] = 'LOWER(a.name) LIKE '.$word;
$wheres[] = implode( ' OR ', $wheres2 );
}
$where = '(' . implode( ($phrase == 'all' ? ') AND (' : ') OR ('), $wheres ) . ')';
break;
}

//ordering of the results
switch ( $ordering ) {

//alphabetic, ascending
case 'alpha':
$order = 'a.name ASC';
break;

//oldest first
case 'oldest':

//popular first
case 'popular':

//newest first
case 'newest':

//default setting: alphabetic, ascending
default:
$order = 'a.name ASC';
}

//replace nameofplugin
$searchNameofplugin = JText::_( 'Nameofplugin' );

//the database query; differs per situation! It will look something like this:
$query = 'SELECT a.name AS title,'
. ' CONCAT_WS( " / ", '. $db->Quote($searchNameofplugin) .', b.title )AS section,'
. ' "1" AS browsernav'
. ' FROM #__nameofplugin AS a'
. ' INNER JOIN #__categories AS b ON b.id = a.catid'
. ' WHERE ( '. $where .' )'
. ' AND a.published = 1'
. ' AND b.access <= '. (int) $user->get( 'aid' )
. ' ORDER BY '. $order
;

//Set query
$db->setQuery( $query, 0, $limit );
$rows = $db->loadObjectList();

//The 'output' of the displayed link
foreach($rows as $key => $row) {
$rows[$key]->href = 'index.php?option=com_newsfeeds&view=newsfeed&catid='.$row->catslug.'&id='.$row->slug;
}

//Return the search results in an array
return $rows;
}</source>

There are 4 variables that get passed in, which are evident by their names and use in the above code.
What's not obvious is what the function should return. An array of objects that the search tool uses to display the results. The results could alternatively have been assembled something like this.
<source lang="PHP">
$rows[] = (object) array(
'href' => 'index.php?option=com_newsfeeds&view=newsfeed&catid='.$row->catslug.'&id='.$row->slug,
'title' => $row['name'],
'section' => $searchnameofplugin,
'created' => $row['date'],
'text' => $row['name'],
'browsernav' => '1'
);
</source>

==INI file(s)==
For internationalization it is good to use the INI files. You can add everything to the language file that 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:
<source lang="INI"># $Id: en-GB.plg_search_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</source>
Of course, you could also add other information, like the author.

For example, this parameter:
<source lang="XML"><param name="search_limit" type="text" size="5" default="50" label="Search Limit"
description="Number of Search items to return"/></source>
Will cause the following output in the INI file:
<source lang="INI">
SEARCH LIMIT=Search Limit
NUMBER OF SEARCH ITEMS TO RETURN=Number of Search items to return</source>
The file looks repetitive, but will be very useful for translaters.

When you want to make your search 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:
<source lang="INI">
SEARCH LIMIT=Zoek limiet
NUMBER OF SEARCH ITEMS TO RETURN=Aantal weer te geven zoekresultaten</source>

==Coding examples==
There are six Joomla! Core Search Plugins. If you look at them you can learn a lot, especially about the query part.
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.
*Plugin Search - Categories
**\plugins\search\categories.XML
**\plugins\search\categories.PHP
**\language\en-GB\en-GB.plg_search_categories.INI
*Plugin Search - Contacts
**\plugins\search\contacts.XML
**\plugins\search\contacts.PHP
**\language\en-GB\en-GB.plg_search_contacts.INI
*Plugin Search - Content
**\plugins\search\content.XML
**\plugins\search\content.PHP
**\language\en-GB\en-GB.plg_search_content.INI
*Plugin Search - Newsfeeds
**\plugins\search\newsfeeds.XML
**\plugins\search\newsfeeds.PHP
**\language\en-GB\en-GB.plg_search_newsfeeds.INI
*Plugin Search - Sections
**\plugins\search\sections.XML
**\plugins\search\sections.PHP
**\language\en-GB\en-GB.plg_search_sections.INI
*Plugin Search - Weblinks
**\plugins\search\weblinks.XML
**\plugins\search\weblinks.PHP
**\language\en-GB\en-GB.plg_search_weblinks.INI

==Quick tips==
*In the PHP file, people often forget to place an semicolon (;) at the end of a row. This causes errors. Check this before you test your plugin.
*Make sure 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_search_nameofplugin.INI

Creating a basic templateDetails.xml file

2010-04-09T17:01:32Z

Dynedain: updating doctype

The <tt>templateDetails.xml</tt> file is essential. Without it, your template won't be seen by Joomla!. The file holds key "metadata" about the template.

Lets look at an example:
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd">
<install version="1.5" type="template">
<name>mynewtemplate</name>
<creationDate>2008-05-01</creationDate>
<author>John Doe</author>
<authorEmail>john@example.com</authorEmail>
<authorUrl>http://www.example.com</authorUrl>
<copyright>John Doe 2008</copyright>
<license>GNU/GPL</license>
<version>1.0.2</version>
<description>My New Template</description>
<files>
<filename>index.php</filename>
<filename>component.php</filename>
<filename>templateDetails.xml</filename>
<filename>template_thumbnail.png</filename>
<filename>images/background.png</filename>
<filename>css/style.css</filename>
</files>
<positions>
<position>breadcrumb</position>
<position>left</position>
<position>right</position>
<position>top</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
<position>footer</position>
</positions>
</install>
</source>
So, as you can see, we have a set of information between markup tags ( the <thing> ). Your best approach is to cut and paste this into your "templateDetails.xml" file and change the relevant bits (such as <name> <author> ).

The <files> part should contain all the files that you use - you possibly don't know what they are called yet - don't worry update it later.

Leave the positions as they are - these are a common set so you will be able to switch easily from the standard templates.

DocType header for templates

2010-04-09T17:00:20Z

Dynedain: /* Joomla Internal XML DocTypes */

Current thinking is that XHTML 1.0 Transitional should be used for Joomla! templates.

===Recommended DocTypes===
{{:Recommended DocTypes|}}

===References about DocTypes===
{{:References about DocTypes|}}

<noinclude>[[Category:Beginners]][[Category:Templates]][[Category:Topics]][[Category:HTML|DocType]][[Category:Template FAQ]]</noinclude>

DocType header for templates

2010-04-09T16:59:35Z

Dynedain: /* Recommended DocTypes */

Current thinking is that XHTML 1.0 Transitional should be used for Joomla! templates.

===Recommended DocTypes===
{{:Recommended DocTypes|}}

===Joomla Internal XML DocTypes===
{{:Official DTDs}}

===References about DocTypes===
{{:References about DocTypes|}}

<noinclude>[[Category:Beginners]][[Category:Templates]][[Category:Topics]][[Category:HTML|DocType]][[Category:Template FAQ]]</noinclude>

Official DTDs

2010-04-09T16:57:40Z

Dynedain:

====Joomla! 1.5 Internal DocTypes====
List of doctypes used by the installation manifest XMLs for Joomla! and 3rd party add-ons.

*Template Manifest (templateDetails.xml): <nowiki><!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd"></nowiki>
*Component Manifest (component-install.xml): <nowiki><!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD component 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/component-install.dtd"></nowiki>
*Plugin Manifest (plugin-install.xml): <nowiki><!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD plugin 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/plugin-install.dtd"></nowiki>
*Module Manifest (module-install.xml): <nowiki><!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD module 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/module-install.dtd"></nowiki>

=====Legacy DTDs=====
Up until December 2008, when dev.joomla.org was shut down, the Internal DTDs were hosted at http://dev.joomla.org/xml/1.5. Since that time, they have been moved to http://www.joomla.org/xml/dtd/1.5 and their locations corrected in Joomla 1.5.9
Some 3rd party Joomla! add-ons may be referencing the old locations, which may work, but is deprecated.

Official DTDs

2010-04-09T16:27:43Z

Dynedain: Updated listings to reflect the shutdown of dev.joomla.org

This is a list of the officially defined public and system identifiers used in Joomla! XML DOCTYPE declarations.

{{Ambox|type=serious|image=serious|text=NOTE: This list is not complete at the present time.}}

;-//Joomla! 1.5//DTD template 1.0//EN
:'''Full DOCTYPE:''' <nowiki><!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd"></nowiki>
:'''URL:''' http://www.joomla.org/xml/dtd/1.5/template-install.dtd
:'''Description:''' Joomla! 1.5 templates for validation of templateDetails.xml files.

;-//Joomla! 1.5//DTD component 1.0//EN
:'''Full DOCTYPE:''' <nowiki><!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD component 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/component-install.dtd"></nowiki>
:'''URL:''' http://www.joomla.org/xml/dtd/1.5/component-install.dtd
:'''Description:''' Joomla! 1.5 templates for validation of component-install.xml files.

;-//Joomla! 1.5//DTD plugin 1.0//EN
:'''Full DOCTYPE:''' <nowiki><!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD plugin 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/plugin-install.dtd"></nowiki>
:'''URL:''' http://www.joomla.org/xml/dtd/1.5/plugin-install.dtd
:'''Description:''' Joomla! 1.5 templates for validation of plugin-install.xml files.

;-//Joomla! 1.5//DTD module 1.0//EN
:'''Full DOCTYPE:''' <nowiki><!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD module 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/module-install.dtd"></nowiki>
:'''URL:''' http://www.joomla.org/xml/dtd/1.5/module-install.dtd
:'''Description:''' Joomla! 1.5 templates for validation of module-install.xml files.

===Legacy DTDs===
Up until December 2008, when dev.joomla.org was shut down, the DTDs were hosted at http://dev.joomla.org/xml/1.5. Since that time, they have been moved to http://www.joomla.org/xml/dtd/1.5
Some 3rd party Joomla! add-ons may be referencing the old locations, which may work, but is deprecated.