Revision as of 15:02, 3 December 2009

This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

This Page Needs Your Help

This page is tagged because itNEEDS REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.More pages that need help similar to this one are here.NOTE-If you feel the need is satistified, please remove this notice.

Contents

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.

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:

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

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.

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]

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.

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

</install>

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.

<?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 accessdefined('_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()))){returnarray();}}//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 inif($text==''){returnarray();}//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 exactcase'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 anycase'all':case'any'://set defaultdefault:$words=explode(' ',$text);$wheres=array();foreach($wordsas$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 resultsswitch($ordering){//alphabetic, ascendingcase'alpha':$order='a.name ASC';break;//oldest firstcase'oldest'://popular firstcase'popular'://newest firstcase'newest'://default setting: alphabetic, ascendingdefault:$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 linkforeach($rowsas$key=>$row){$rows[$key]->href='index.php?option=com_newsfeeds&view=newsfeed&catid='.$row->catslug.'&id='.$row->slug;}//Return the search results in an arrayreturn$rows;}

There are 4 variables that get passed it, which are evident by their names and use in the 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.