Actions

J1.5

Difference between revisions of "Creating a search plugin"

From Joomla! Documentation

Line 51: Line 51:
  
 
==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 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
 
<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 58: Line 59:
 
  * @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' );
 +
 
 +
//Now define the registerEvent and the language file. Replace 'nameofplugin' by 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.
+
//Then define a function to return an array of search areas. Replace 'nameofplugin' by the name of your Plugin.
<source lang="PHP">function &plgSearchnameofpluginAreas()
+
function &plgSearchnameofpluginAreas()
 
{
 
{
 
static $areas = array(
 
static $areas = array(
Line 76: Line 78:
 
);
 
);
 
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 )
+
//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();
 
$db =& JFactory::getDBO();
$user =& JFactory::getUser(); </source>
+
$user =& JFactory::getUser();  
When the array is not correct, return it:
+
//When the array is not correct, return it:
<source lang="PHP"> if (is_array( $areas )) {
+
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">
+
//And yet it is the time to 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..
+
//And define the parameters. For example like this..
 
+
<source lang="PHP">
+
 
$limit = $pluginParams->def( 'nameofparameter', defaultsetting );
 
$limit = $pluginParams->def( 'nameofparameter', defaultsetting );
</source>
 
 
Use the function trim to delete spaces in front of or at the back of the searching terms
 
  
<source lang="PHP">
+
//Use the function trim to delete spaces in front of or at the back of the searching terms
 
$text = trim( $text );
 
$text = trim( $text );
</source>
 
  
Return when nothing was filled in
+
//Return when nothing was filled in
<source lang="PHP">
+
 
if ($text == '') {
 
if ($text == '') {
 
return array();
 
return array();
}</source>
+
}
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.
+
//After this, you have to add the database part. This will be the most difficult part, because this changes per situation.
Although, it will look something like this. Explanation is added within the PHP quotes.
+
//In the coding examples later on you will find some of the examples used by Joomla! 1.5 core Search Plugins.
<source lang="PHP">$wheres = array();
+
//It will look something like this.
 +
$wheres = array();
 
switch ($phrase) {
 
switch ($phrase) {
 +
 
//search exact
 
//search exact
 
case 'exact':
 
case 'exact':
Line 127: Line 122:
 
$where = '(' . implode( ') OR (', $wheres2 ) . ')';
 
$where = '(' . implode( ') OR (', $wheres2 ) . ')';
 
break;
 
break;
 +
 
//search all or any
 
//search all or any
 
case 'all':
 
case 'all':
 
case 'any':
 
case 'any':
 +
 
//set default
 
//set default
 
default:
 
default:
Line 144: Line 141:
 
break;
 
break;
 
}
 
}
 +
 
//ordering of the results
 
//ordering of the results
 
switch ( $ordering ) {
 
switch ( $ordering ) {
 +
 
//alphabetic, ascending
 
//alphabetic, ascending
 
case 'alpha':
 
case 'alpha':
 
$order = 'a.name ASC';
 
$order = 'a.name ASC';
 
break;
 
break;
 +
 
//oldest first
 
//oldest first
 
case 'oldest':
 
case 'oldest':
 +
 
//popular first
 
//popular first
 
case 'popular':
 
case 'popular':
 +
 
//newest first
 
//newest first
 
case 'newest':
 
case 'newest':
 +
 
//default setting: alphabetic, ascending
 
//default setting: alphabetic, ascending
 
default:
 
default:
 
$order = 'a.name ASC';
 
$order = 'a.name ASC';
 
}
 
}
 +
 
//replace nameofplugin
 
//replace nameofplugin
 
$searchnameofplugin = JText::_( 'Nameofplugin' );
 
$searchnameofplugin = JText::_( 'Nameofplugin' );
 +
 
//the database query; differs per situation! It will look something like this:
 
//the database query; differs per situation! It will look something like this:
 
$query = 'SELECT a.name AS title'
 
$query = 'SELECT a.name AS title'
Line 173: Line 178:
 
. ' ORDER BY '. $order
 
. ' ORDER BY '. $order
 
;
 
;
 +
 
//Set query
 
//Set query
 
$db->setQuery( $query, 0, $limit );
 
$db->setQuery( $query, 0, $limit );
 
$rows = $db->loadObjectList();
 
$rows = $db->loadObjectList();
 +
 
//the 'output' of the displayed link
 
//the 'output' of the displayed link
 
foreach($rows as $key => $row) {
 
foreach($rows as $key => $row) {
 
$rows[$key]->href = 'index.php?option=com_newsfeeds&view=newsfeed&catid='.$row->catslug.'&id='.$row->slug;
 
$rows[$key]->href = 'index.php?option=com_newsfeeds&view=newsfeed&catid='.$row->catslug.'&id='.$row->slug;
}</source>
+
}
And end your plugin with
+
 
<source lang="PHP">
+
//And end your plugin with
 
return $rows;
 
return $rows;
 
}</source>
 
}</source>
Line 191: Line 198:
 
*JText::_( 'string' ) used by the plugin
 
*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 =, like this:
 +
<source lang="INI">
 +
SEARCH LIMIT=Search limit in another language
 +
NUMBER OF SEARCH ITEMS TO RETURN=Number of Search items to return in another language</source>
  
 
==Coding examples==
 
==Coding examples==

Revision as of 15:51, 19 January 2008

Replacement filing cabinet.png
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.
Quill icon.png
Page Actively Being Edited!

This j1.5 page is actively undergoing a major edit for a short while.
As a courtesy, please do not edit this page while this message is displayed. The user who added this notice will be listed in the page history. This message is intended to help reduce edit conflicts; please remove it between editing sessions to allow others to edit the page. If this page has not been edited for several hours, please remove this template, or replace it with {{underconstruction}} or {{incomplete}}.

Contents

Description

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 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, like this:

<name>Name of your Search 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 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="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.

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 access
defined( '_JEXEC' ) or die( 'Restricted access' );
 
//Now define the registerEvent and the language file. Replace 'nameofplugin' by 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' by 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(); 
//When the array is not correct, return it:
        if (is_array( $areas )) {
                if (!array_intersect( $areas, array_keys( plgSearchnameofpluginAreas() ) )) {
                        return array();
                }
        }
 
//And yet it is the 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 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;
        }
 
//And end your plugin with
return $rows;
}

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_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 translaters.

When you want to make your Search Plugin available in more languages, first add them to the