Joomla! Documentation™

Joomla! 

3.x

serie

Beschrijving

Dit document behandelt het maken van een zoek plugin. U kunt een zoek plugin gebruiken om de database van uw Joomla! website te doorzoeken. Om een plugin te maken, heeft u ten minste twee bestanden nodig: een XML-bestand en een PHP-bestand. Om de plugin internationaal te gebruiken is het aan te bevelen om ook een INI-bestand te maken.

XML-bestand

Het XML bestand heeft dezelfde naam als het PHP-bestand, en is een van de twee benodigde bestanden. Begin altijd met de XML-tag en geef aan dat het geschreven is in een UTF-8 format.

<?xml version="1.0" encoding="utf-8"?>

Om aan te geven dat de plugin een zoek plugin moet zijn, voegt u deze regel toe

<extension version="3.1" type="plugin" group="search">

Type geeft aan dat het een plugin is, group dat de plugin tot de groep van zoek plugins behoort.

Voeg daarna enige informatie toe over uzelf en over de 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>

Voeg nu uw PHP-bestand toe aan de zoek plugin. De naam van dit bestand moet hetzelfde zijn als die van het XML-bestand. Zet deze naam ook achter het plugin="" gedeelte.

U kunt meer bestanden toevoegen voor uw plugin, een afbeelding bijvoorbeeld. Voeg een extra rij toe tussen <files> en </files> en zet de bestandsnaam tussen <filename> tags.

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

We gebruiken taalbestanden voor internationaal gebruik. Dit is niet verplicht, maar mensen uit andere landen zullen het fijn vinden als ze uw plugin gemakkelijk kunnen vertalen naar hun eigen taal. De taal-tags vindt u hier: [1] (gebruik de ISO 639-1 kolom) en hier: [2]

<languages>
   <language tag="en-GB">language/en-GB/en-GB.plg_search_nameofplugin.ini</language>
</languages>

Optioneel kunt u een aantal parameters toevoegen aan de plugin. Die zullen er zo uitzien:

	<config>
		<fields name="params">

			<fieldset name="basic">
				<field name="search_limit" type="text"
					default="50"
					description="JFIELD_PLG_SEARCH_SEARCHLIMIT_DESC"
					label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
					size="5"
				/>

				<field name="search_content" type="radio"
					default="0"
					description="JFIELD_PLG_SEARCH_ALL_DESC"
					label="JFIELD_PLG_SEARCH_ALL_LABEL"
				>
					<option value="0">JOFF</option>
					<option value="1">JON</option>
				</field>

			</fieldset>
		</fields>
	</config>

Vergeet niet uw XML-bestand af te sluiten met de volgende tag:

</extension>

PHP-bestand

Het PHP-bestand is het belangrijkste bestand van de plugin. Dit is een voorbeeld van een PHP-bestand van een zoek plugin. De commentaren zijn erin meegenomen.

<?php
//First start with information about the Plugin and yourself. For example:
/**
 * @package     Joomla.Plugin
 * @subpackage  Search.nameofplugin
 *
 * @copyright   Copyright
 * @license     License, for example GNU/GPL
 */

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

// Require the component's router file (Replace 'nameofcomponent' with the component your providing the search for
require_once JPATH_SITE .  '/components/nameofcomponent/helpers/route.php';

/**
 * All functions need to get wrapped in a class
 *
 * The class name should start with 'PlgSearch' followed by the name of the plugin. Joomla calls the class based on the name of the plugin, so it is very important that they match
 */
class PlgSearchNameofplugin extends JPlugin
{
	/**
	 * Constructor
	 *
	 * @access      protected
	 * @param       object  $subject The object to observe
	 * @param       array   $config  An array that holds the plugin configuration
	 * @since       1.6
	 */
	public function __construct(& $subject, $config)
	{
		parent::__construct($subject, $config);
		$this->loadLanguage();
	}

	// Define a function to return an array of search areas. Replace 'nameofplugin' with the name of your plugin.
	// Note the value of the array key is normally a language string
	function onContentSearchAreas()
	{
		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.
	/**
	 * The sql must return the following fields that are used in a common display
	 * routine: href, title, section, created, text, browsernav
	 *
	 * @param string Target search string
	 * @param string mathcing option, exact|any|all
	 * @param string ordering option, newest|oldest|popular|alpha|category
	 * @param mixed An array if the search it to be restricted to areas, null if search all
	 */
	function onContentSearch( $text, $phrase='', $ordering='', $areas=null )
	{
		$user	= JFactory::getUser(); 
		$groups	= implode(',', $user->getAuthorisedViewLevels());

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

		// Now retrieve the plugin parameters like this:
		$nameofparameter = $this->params->get('nameofparameter', defaultsetting );

		// Use the PHP 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! 3.1 core Search Plugins.
		//It will look something like this.
		$wheres = array();
		switch ($phrase) {

			// Search exact
			case 'exact':
				$text		= $this->db->Quote( '%'.$this->db->escape( $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		= $this->db->Quote( '%'.$this->db->escape( $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
		$section = JText::_( 'Nameofplugin' );

		// The database query; differs per situation! It will look something like this (example from newsfeed search plugin):
		$query	= $this->db->getQuery(true);
		$query->select('a.name AS title, "" AS created, a.link AS text, ' . $case_when."," . $case_when1);
				$query->select($query->concatenate(array($this->db->Quote($section), 'c.title'), " / ").' AS section');
				$query->select('"1" AS browsernav');
				$query->from('#__nameofcomponent AS a');
				$query->innerJoin('#__categories as c ON c.id = a.catid');
				$query->where('('. $where .')' . 'AND a.published IN ('.implode(',', $state).') AND c.published = 1 AND c.access IN ('. $groups .')');
				$query->order($order);

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

		// The 'output' of the displayed link. Again a demonstration from the newsfeed search plugin
		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;
	}
}

Er zijn vier variabelen die worden meegenomen. Ze zijn duidelijk door hun namen en het gebruik in de bovenstaande code. Wat niet duidelijk is, is wat de functie moet laten zien: een lijst van objecten die de zoekmachine gebruikt om de resultaten te laten zien. De resultaten zouden ook op deze manier samengesteld kunnen zijn.

$rows[] = (object) array(
			'href'        => 'index.php?option=com_newsfeeds&view=newsfeed&catid='.$row->catslug.'&id='.$row->slug,
			'title'       => $row['name'],
			'section'     => $nameofcomponent,
			'created'     => $row['date'],
			'text'        => $row['name'],
			'browsernav'  => '1'
		);

INI-bestanden

Voor internationaal gebruik is het aan te bevelen om de INI-bestanden te gebruiken. Aan het taalbestand kunt u alles toevoegen dat tekst aan de gebruiker laat zien, in deze volgorde:

• XML description tag
• XML label en beschrijving van kenmerken (attributes) van de parameters
• JText::_( 'string' ) die de plugin gebruikt

Begin uw INI-bestand met iets als dit:

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

U kunt natuurlijk ook andere informatie toevoegen, zoals de auteur.

Deze parameter bijvoorbeeld:

<field name="search_limit" type="text"
  default="50"
  description="JFIELD_PLG_SEARCH_SEARCHLIMIT_DESC"
  label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
  size="5"
/>

zal in het INI-bestand de volgende uitvoer laten zien:

JFIELD_PLG_SEARCH_SEARCHLIMIT_DESC=Search Limit
JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL=Number of Search items to return

Het bestand ziet er repetitief uit, maar is bijzonder nuttig voor vertalers.

Als u uw zoek plugin beschikbaar wilt maken in meerdere talen, voeg die dan eerst toe aan de languages tag in het XML-bestand. Maak dan hetzelfde INI-bestand en verander het gedeelte na =. De Nederlandse versie zou bijvoorbeeld zijn:

JFIELD_PLG_SEARCH_SEARCHLIMIT_DESC=Zoek limiet
JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL=Aantal weer te geven zoekresultaten

Snelle tips

• In PHP-bestanden vergeten mensen vaak een puntkomma (;) te plaatsen aan het eind van een regel. Dit veroorzaakt fouten. Controleer dit voor u uw plugin gaat testen.
• Zorg ervoor dat de parameters in het XML-bestand correct afgesloten zijn. Als u bijvoorbeeld een optie toevoegt, moet u die afsluiten met </param>.
• Het is gemakkelijk om op een localhost te testen als u uw plugin aan het bewerken bent.
• Wanneer u een zip-bestand maakt, vergeet dan niet om de mappen voor de taalbestanden aan te maken. Een plugin zip-bestand bevat meestal het volgende:

• • nameofplugin.xml
  • nameofplugin.php
  • language\en-GB\en-GB.plg_search_nameofplugin.ini