J1.5

Difference between revisions of "Creating a search plugin"

From Joomla! Documentation

(Remove 2.5 stuff)
 
(38 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{inuse}}
+
{{version/tutor|1.5}}
 
==Description==
 
==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==
 
==XML file==
 
The XML file is named the same as the PHP file, and is one of the two required files.
 
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.
 
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"?></source>
+
 
To define that the plugin has to be a search plugin, add this line:
+
<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"></source>
 +
 
 +
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>
 
<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:
+
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:
 
<source lang="xml">
 
<source lang="xml">
<name>Name of your Search Plugin</name>
+
<name>Name of your search plugin</name>
 +
<creationDate>Creation date</creationDate>
 
<author>Your name</author>
 
<author>Your name</author>
<creationDate>Created Date</creationDate>
 
<copyright>Copyright</copyright>
 
<license>License, for example GNU/GPL</license>
 
 
<authorEmail>Your e-mail address</authorEmail>
 
<authorEmail>Your e-mail address</authorEmail>
 
<authorUrl>Your website</authorUrl>
 
<authorUrl>Your website</authorUrl>
 +
<copyright>Copyright information</copyright>
 +
<license>License, for example GNU/GPL</license>
 
<version>Version of the plugin</version>
 
<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>
+
<description>Description of the plugin; shown during installation and when editing  
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.  
+
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.
+
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">
 
<source lang="xml">
 
<files>
 
<files>
 
   <filename plugin="nameofplugin">nameofplugin.php</filename>
 
   <filename plugin="nameofplugin">nameofplugin.php</filename>
 
</files></source>
 
</files></source>
Optionally, you could add some parameters to the Plugin. These will look like this:
+
 
 +
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">
 
<source lang="xml">
 
<params>
 
<params>
   <param name="paramname" type="typeofparameter" default="defaultsetting" label="title" description="description"/>
+
   <param name="search_limit" type="text"
 +
    default="50"
 +
    description="JFIELD_PLG_SEARCH_SEARCHLIMIT_DESC"
 +
    label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
 +
    size="5"
 +
    />
 
</params></source>
 
</params></source>
 
*'''Param name:''' The name of the parameter. You will need this when creating the PHP file.
 
*'''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. For example, "text" is used to display an input box.
+
*'''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 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 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.  
 
*'''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:
+
Do not forget to end your XML file with the following tag
 +
 
 
<source lang="xml"></install></source>
 
<source lang="xml"></install></source>
  
 
==PHP file==
 
==PHP file==
The PHP file of your Plugin is probably the most important file of the Plugin. First start with information about the Plugin and yourself. For example:
+
The PHP file of your plugin is 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
 
<source lang="PHP"><?php
 +
//First start with information about the Plugin and yourself. For example:
 
/**
 
/**
 
  * @version $Id: nameofplugin.php versionnumber date author
 
  * @version $Id: nameofplugin.php versionnumber date author
Line 50: Line 74:
 
  * @license License, for example GNU/GPL
 
  * @license License, for example GNU/GPL
 
  * All other information you would like to add
 
  * All other information you would like to add
  */</source>
+
  */
To prevent accessing the document directly, enter this code:
 
<source lang="PHP">// no direct access
 
defined( '_JEXEC' ) or die( 'Restricted access' );</source>
 
  
Now define the registerEvent and the language file. Replace 'nameofplugin' by the name of your Plugin.
+
//To prevent accessing the document directly, enter this code:
<source lang="PHP">$mainframe->registerEvent( 'onSearch', 'plgSearchnameofplugin' );
+
// no direct access
 +
defined( '_JEXEC' ) or die( 'Restricted access' );
 +
 
 +
//Define the registerEvent and the language file. Replace 'nameofplugin' with the name of your plugin.
 +
$mainframe->registerEvent( 'onSearch', 'plgSearchnameofplugin' );
 
$mainframe->registerEvent( 'onSearchAreas', 'plgSearchnameofpluginAreas' );
 
$mainframe->registerEvent( 'onSearchAreas', 'plgSearchnameofpluginAreas' );
  
JPlugin::loadLanguage( 'plg_search_nameofplugin' );</source>
+
JPlugin::loadLanguage( 'plg_search_nameofplugin' );
  
Then define a function to return an array of search areas. Replace 'nameofplugin' by the name of your Plugin.
+
//Define a function to return an array of search areas. Replace 'nameofplugin' with the name of your plugin.
<source lang="PHP">function &plgSearchnameofpluginAreas()
+
function &plgSearchnameofpluginAreas()
 
{
 
{
 
static $areas = array(
 
static $areas = array(
Line 68: Line 93:
 
);
 
);
 
return $areas;
 
return $areas;
}</source>
+
}
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.
+
 
<source lang="PHP">function plgSearchnameofplugin( $text, $phrase='', $ordering='', $areas=null )
+
//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();
 
$db =& JFactory::getDBO();
$user =& JFactory::getUser(); </source>
+
$user =& JFactory::getUser();  
When the array is not correct, return it:
+
 
<source lang="PHP"> if (is_array( $areas )) {
+
//If the array is not correct, return it:
 +
if (is_array( $areas )) {
 
if (!array_intersect( $areas, array_keys( plgSearchnameofpluginAreas() ) )) {
 
if (!array_intersect( $areas, array_keys( plgSearchnameofpluginAreas() ) )) {
 
return array();
 
return array();
 
}
 
}
}</source>
+
}
And yet it is the time to define the parameters! First get the right plugin; 'search' (the group), 'nameofplugin'.  
+
 
<source lang="PHP">
+
//Define the parameters. First get the right plugin; 'search' (the group), 'nameofplugin'.  
 
$plugin =& JPluginHelper::getPlugin('search', 'nameofplugin');
 
$plugin =& JPluginHelper::getPlugin('search', 'nameofplugin');
</source>
 
  
Then load the parameters of the Plugin..
+
//Then load the parameters of the plugin.
<source lang="PHP">
 
 
$pluginParams = new JParameter( $plugin->params );
 
$pluginParams = new JParameter( $plugin->params );
</source>
 
  
And define the parameters. For example like this..
+
//Now define the parameters 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 four variables that get passed in. They 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 like this.
 
<source lang="PHP">
 
<source lang="PHP">
$limit = $pluginParams->def( 'nameofparameter', defaultsetting );
+
$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>
 
</source>
  
Use the function trim to delete spaces in front of or at the back of the searching terms
+
==INI file(s)==
 +
{{JVer|1.5}}
 +
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
  
<source lang="PHP">
+
Start your INI file with something like this:
$text = trim( $text );
+
<source lang="INI"># $Id: en-GB.plg_search_nameofplugin.ini
</source>
+
# 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 translators.
  
==INI file(s)==
+
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==
 
==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. 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
  
==Points to watch==
+
==Quick tips==
 +
*In the PHP file, people often forget to place a semicolon (;) at the end of a line. This causes errors. Check this before you test your plugin.
 +
*Make sure the parameters in the XML file are closed correctly. When you add an option, for example, you need to close it with </param>.
 +
*It is easy to test on a localhost when you are editing your plugin.
 +
*When making a zip-file,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
  
==Dependencies==
+
[[Category:Archive Joomla 1.5]]

Latest revision as of 15:01, 26 August 2013

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.

Description[edit]

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[edit]

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://www.joomla.org/xml/dtd/1.5/plugin-install.dtd">

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

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

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:

<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; shown during installation and when editing 
the plugin in the Plugin Manager</description>

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.

<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_search_nameofplugin.ini</language>
</languages>

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

<params>
   <param name="search_limit" type="text"
     default="50"
     description="JFIELD_PLG_SEARCH_SEARCHLIMIT_DESC"
     label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
     size="5"
    />
</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.

Do not forget to end your XML file with the following tag

</install>

PHP file[edit]

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

<?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' );

//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' );

//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;
}

//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();
		}
	}

//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 );

//Now define the parameters 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;
}

There are four variables that get passed in. They 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 like this.

$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'
		);

INI file(s)[edit]

Joomla 1.5 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:

# $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

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

For example, this parameter:

<param name="search_limit" type="text" size="5" default="50" label="Search Limit" 
description="Number of Search items to return"/>

Will cause the following output in the INI file:

SEARCH LIMIT=Search Limit
NUMBER OF SEARCH ITEMS TO RETURN=Number of Search items to return

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

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:

SEARCH LIMIT=Zoek limiet
NUMBER OF SEARCH ITEMS TO RETURN=Aantal weer te geven zoekresultaten

Coding examples[edit]

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. 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[edit]

  • In the PHP file, people often forget to place a semicolon (;) at the end of a line. This causes errors. Check this before you test your plugin.
  • Make sure the parameters in the XML file are closed correctly. When you add an option, for example, you need to close it with </param>.
  • It is easy to test on a localhost when you are editing your plugin.
  • When making a zip-file,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