Joomla! Documentation - User contributions [en]

API17:JRequest::getVar

2012-07-01T10:12:42Z

BastianW: /* User contributed notes */ added example

__NOTOC__
=={{JVer|11.1}} JRequest::getVar==
===Description===
Fetches and returns a given variable.

{{Description:JRequest::getVar}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JRequest::getVar|Edit Descripton]]<nowiki>]</nowiki>
</span>
<source lang="php">
public static function getVar (
$name
$default=null
$hash= 'default'
$type= 'none'
$mask=0
)
</source>
{| class="wikitable"
|-
!Parameter
!Type
!Default
!Description
|-
|$name
|
|
|
|-
|$default
|
|null
|
|-
|$hash
|
|'default'
|
|-
|$type
|
|'none'
|
|-
|$mask
|
|0
|
|-
|}
* '''Returns'''
* '''Defined''' on line 92 of libraries/joomla/environment/request.php
* '''Referenced by'''
** [[JSession::_start/11.1|JSession::_start]]
** [[JControllerAdmin::checkin/11.1|JControllerAdmin::checkin]]
** [[JControllerAdmin::delete/11.1|JControllerAdmin::delete]]
** [[JControllerForm::edit/11.1|JControllerForm::edit]]
** [[JController::getInstance/11.1|JController::getInstance]]
** [[JModelList::getUserStateFromRequest/11.1|JModelList::getUserStateFromRequest]]
** [[JCache::makeId/11.1|JCache::makeId]]
** [[JControllerAdmin::publish/11.1|JControllerAdmin::publish]]
** [[JControllerAdmin::reorder/11.1|JControllerAdmin::reorder]]
** [[JControllerForm::save/11.1|JControllerForm::save]]
** [[JControllerAdmin::saveorder/11.1|JControllerAdmin::saveorder]]
===See also===
* {{JVer|11.1}} '''JRequest::getVar source code''' on [[jplatform:environment/request.php#cl-84|BitBucket]]
* {{JVer|11.1}} Class [[JRequest/11.1|JRequest]]
* {{JVer|11.1}} Subpackage [[Subpackage_Environment/11.1|Environment]]
* [[JRequest::getVar|Other versions of JRequest::getVar]]
{{SeeAlso:JRequest::getVar}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JRequest::getVar|Edit See Also]]<nowiki>]</nowiki>
</span>
===User contributed notes===
===Example===
<source lang="php">
//Retrieve file details from uploaded file, sent from upload form
$file = JRequest::getVar('upload_file', null, 'files', 'array');
</source>

<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=JRequest::getVar
category=CodeExample
category=MethodExample
include=*
namespace=CodeExample
format= ,,,
</dpl>
<noinclude>[[Category:JRequest]][[Category:JRequest::getVar]]</noinclude>

API17:JFile::makeSafe

2012-07-01T09:02:40Z

BastianW: /* User contributed notes */ added example

__NOTOC__
=={{JVer|11.1}} JFile::makeSafe==
===Description===
Makes file name safe to use.

{{Description:JFile::makeSafe}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JFile::makeSafe|Edit Descripton]]<nowiki>]</nowiki>
</span>
<source lang="php">
public static function makeSafe ($file)
</source>
{| class="wikitable"
|-
!Parameter
!Type
!Default
!Description
|-
|$file
|string
|
|The name of the file [not full path]
|-
|}
* '''Returns''' string The sanitised string
* '''Defined''' on line 60 of libraries/joomla/filesystem/file.php
* '''Since''' {{JVer|11.1 }}
===See also===
* {{JVer|11.1}} '''JFile::makeSafe source code''' on [[jplatform:filesystem/file.php#cl-52|BitBucket]]
* {{JVer|11.1}} Class [[JFile/11.1|JFile]]
* {{JVer|11.1}} Subpackage [[Subpackage_Filesystem/11.1|Filesystem]]
* [[JFile::makeSafe|Other versions of JFile::makeSafe]]
{{SeeAlso:JFile::makeSafe}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JFile::makeSafe|Edit See Also]]<nowiki>]</nowiki>
</span>
===User contributed notes===
===Example===
<source lang="php">
//Retrieve file details from uploaded file, sent from upload form
$file = JRequest::getVar('upload_file', null, 'files', 'array');

//Import filesystem libraries. Perhaps not necessary, but does not hurt
jimport('joomla.filesystem.file');

//Clean up filename to get rid of strange characters like spaces etc
$filename = JFile::makeSafe($file['name']);
</source>

<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=JFile::makeSafe
category=CodeExample
category=MethodExample
include=*
namespace=CodeExample
format= ,,,
</dpl>
<noinclude>[[Category:JFile]][[Category:JFile::makeSafe]]</noinclude>

How to use the filesystem package

2012-07-01T08:56:43Z

BastianW: /* Example */ added note that enctype="multipart/form-data" is a must have here.

=Using the JFILE:: class=

There are 4 classes in the J15 filesystem library.

* JFile:: (file.php)
* JFolder:: (folder.php)
* JPath:: (path.php)
* JArchive:: (archive.php)[/i]

For this first tutorial, I will focus on the JFile:: class.

The base for filehandling is the JFile class, found in libraries/joomla/filesystem/file.php
Below I will discuss the most common options from this library file. At the end of this post, I put it together in a very simple script for file upload.

==Get file extension==
Syntax:
<source lang=php>
$ext = JFile::getExt($filename);
</source>

Pretty clear, just feed the function with a filename and it will return the extension of the file you selected.

==Strip file extension==
Syntax:
<source lang=php>
$name = JFile::stripExt($filename);
</source>
This will return the filename without the extension.

==Clean filename==
Syntax:
<source lang=php>
$safefilename = JFile::makeSafe($filename);
</source>
It cleans out all odd characters from a filename and returns a safe filename.

==Copy a file==
Syntax:
<source lang=php>
JFile::copy($src, $dest);
</source>
It is basically a wrapper for the PHP copy() function, but also checks if the file you want to copy exists and the destination really is available. Great thing is that this function also makes use of the FTP-layer in J15 if necessary.

==Delete a file==
Syntax:
<source lang=php>
JFile::delete($path.$file);
</source>
It tries to delete the file, making sure it is actually existing, but also checks permissions. If permissions are not set up properly, it tries to change them and delete the file. It also uses the FTP-layer when necessary.

==Upload a file==
Syntax:
<source lang=php>
JFile::upload($src, $dest);
</source>
It is basically the wrapper for the PHP move_uploaded_file() function, but also does checks availability and permissions on both source and destination path.

==Example==
So how does that look in a script? I put up a small code snippet of an upload script. Some of the functions are used.
The script is fired from an upload form. That form has a file element, called file_upload (see below).
<source lang=php>
<form name="upload" method="post" enctype="multipart/form-data">
<input type="file" name="file_upload" />
<input type="submit" />
</form>
</source>

Note:
If you didn´t add the part: enctype="multipart/form-data" then you are unable to upload a file!

Upload code looks like this:
<source lang=php>
<?php
***********************
* *
* File upload example *
* *
***********************
//Retrieve file details from uploaded file, sent from upload form
$file = JRequest::getVar('file_upload', null, 'files', 'array');

//Import filesystem libraries. Perhaps not necessary, but does not hurt
jimport('joomla.filesystem.file');

//Clean up filename to get rid of strange characters like spaces etc
$filename = JFile::makeSafe($file['name']);

//Set up the source and destination of the file
$src = $file['tmp_name'];
$dest = JPATH_COMPONENT . DS . "uploads" . DS . $filename;

//First check if the file has the right extension, we need jpg only
if ( strtolower(JFile::getExt($filename) ) == 'jpg') {
if ( JFile::upload($src, $dest) ) {
//Redirect to a page of your choice
} else {
//Redirect and throw an error message
}
} else {
//Redirect and notify user file is not right extension
}
?>
</source>

=Upload - Full Sample=

Little sample where admin choose the file type or all, enter the users to access the form upload.
Folder to upload files in Joomla directory or with absolute path.
Only selected users access the form upload.

mod_simpleupload.xml
<source lang=xml>
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
<name>Simple Upload 1.3</name>
<author>Ribamar FS</author>
<creationDate>fevereiro 2010</creationDate>
<copyright>(C) 2005 Open Source Matters. All rights reserved.</copyright>
<license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
<authorEmail>ribafs@gmail.com</authorEmail>
<authorUrl>http://ribafs.org</authorUrl>
<version>1.3</version>
<description>Simple Upload 1.3 - Simple upload with Joomla Framework.</description>
<files>
<filename module="mod_simpleupload">mod_simpleupload.php</filename>
</files>
<params>
<param name="dir" type="text" label="Directory" description="Directory Upload" default="upload"/>
<param name="type" type="list" default="*" label="Select a file type" description="File type">
<option value="*">Any File </option>
<option value="image/png">PNG</option>
<option value="image/gif">GIF</option>
<option value="image/jpeg">JPEG</option>
<option value="application/zip">ZIP</option>
<option value="application/x-gzip">TAR.GZ</option>
<option value="text/html">HTML</option>
<option value="text/plain">TXT</option>
<option value="application/pdf">PDF</option>
<option value="application/msword">DOC</option>
</param>
<param name="user_names" type="text" label="User Names (optional)" description="Names users (optionas)" default=""/>
</params>
</install>
</source>

mod_simpleupload.php
<source lang=php>
<?php
// no direct access
defined('_JEXEC') or die('Restricted access');

//Import filesystem libraries. Perhaps not necessary, but does not hurt
jimport('joomla.filesystem.file');

$max = ini_get('upload_max_filesize');
$module_dir = $params->get( 'dir' );
$file_type = $params->get( 'type' );

$user_names = $params->get( 'user_names' );
$msg = '';

function fileUpload($max, $module_dir, $file_type, $msg){
//Retrieve file details from uploaded file, sent from upload form
$file = JRequest::getVar('file_upload', null, 'files', 'array');
// Retorna: Array ( [name] => mod_simpleupload_1.2.1.zip [type] => application/zip
// [tmp_name] => /tmp/phpo3VG9F [error] => 0 [size] => 4463 )

if(isset($file)){
//Clean up filename to get rid of strange characters like spaces etc
$filename = JFile::makeSafe($file['name']);

if($file['size'] > $max) $msg = JText::_('ONLY_FILES_UNDER').' '.$max;
//Set up the source and destination of the file

$src = $file['tmp_name'];
$dest = $module_dir . DS . $filename;

//First check if the file has the right extension, we need jpg only
if ($file['type'] == $file_type || $file_type == '*') {
if ( JFile::upload($src, $dest) ) {

//Redirect to a page of your choice
$msg = JText::_('FILE_SAVE_AS').' '.$dest;
} else {
//Redirect and throw an error message
$msg = JText::_('ERROR_IN_UPLOAD');
}
} else {
//Redirect and notify user file is not right extension
$msg = JText::_('FILE_TYPE_INVALID');
}

$msg = "<script>alert('". $msg ."');</script>";
}
return $msg;
}

$user =& JFactory::getUser();
$username = $user->get('username');

$acc = 0;
$session =& JFactory::getSession();

if(isset($user_names)) {
$more = strpos($user_names, ',',0);
if($more >0){
$user_names = explode(',',$user_names);
foreach($user_names as $un){
if($un == $username) {
$session->set($acc, 1);
}else{
$session->set($acc, 0);
}
}
}else{
if ($user_names == $username) $session->set($acc, 1);
}
}else{
if(isset($username)) $session->set($acc, 1);
}

if($session->get($acc) == 1){
?>

<form name="imgform" method="post" action="" enctype="multipart/form-data" onSubmit="if(file_upload.value=='') {alert('Choose a file!');return false;}">
<?php echo JText::_('CHOOSE_FILE'); ?> <input type="file" name="file_upload" size="10" />
<input name="submit" type="submit" value="Upload" />
</form>

<?php
print fileUpload($max, $module_dir, $file_type, $msg);
}

// Adapted from http://docs.joomla.org/How_to_use_the_filesystem_package
?>
</source>

=Using the JFolder:: class=
The base for folder handling is the JFolder class, found in libraries/joomla/filesystem/folder.php
Below I will discuss the most common options from this library file. At the end of this post, I put it together in a very simple script as an exmaple

==Copy folder==
Syntax:
<source lang=php>
JFolder::copy($src, $dest, $path, $force);
</source>
This will copy a complete folder and all of it’s contents to another location on the server. It does permission and availability checking on both source and destination. By using $path you can enter a basepath to prefix to the filename and by setting the $force parameter to true, you can force the overwriting of already existing files. If set in the configuration, the FTP-layer will be used.

==Create folder==
Syntax:
<source lang=php>
JFolder::create($path, $mode);
</source>
This is basically a wrapper for the php mkdir() function, but with error permissions and availability checking. This one also uses the FTP-layer when set in the configuration. $mode will set the default permission, once copied and defaults to 0755.

==Move folder==
Syntax:
<source lang=php>
JFolder::move($src, $dest);
</source>
Basically a wrapper for the php rename() function, but with permissions and availability checking. This one also uses the FTP-layer when set in the configuration.

==Check if folder exists==
Syntax:
<source lang=php>
JFolder::exists($path);
</source>
Wrapper for the php is_dir() function. Pretty straightforward, returns true if folder exists.

==Read files from folder==
Syntax:
<source lang=php>
JFolder::files($path, $filter = '.', $recurse, $fullpath , $exclude);
</source>
Function to read files from a folder. When setting $recurse to true, also subfolders will be searched. $fullpath set to true returns the full path in the array. With $exclude, you can offer an array of extensions, not to include in the search for files. It returns an array with all filenames.

==Read folders from filesystem==
Syntax:
<source lang=php>
JFolder::folders($path, $filter = '.', $recurse, $fullpath , $exclude);
</source>
Exactly the same as JFolder::files(), except this does only return an array with foldernames.

==Make a tree like list from a folder structure==
Syntax:
<source lang=php>
JFolder::listFolderTree($path, $filter, $maxLevel = 3, $level = 0, $parent = 0);
</source>
It will read a folder, specified in $path and will return all folders in an array, suitable for tree display. You can specify the number of levels. The folder array looks like this:
<source lang=php>
Array
(
[0] => Array
(
[id] => 1
[parent] => 0
[name] => administrator
[fullname] => g:/joomla_1012/administrator
[relname] => g:/joomla_1012/administrator
)

[1] => Array
(
[id] => 2
[parent] => 1
[name] => backups
[fullname] => g:/joomla_1012/administrator/backups
[relname] => g:/joomla_1012/administrator/backups
)

[2] => Array
(
[id] => 3
[parent] => 1
[name] => components
[fullname] => g:/joomla_1012/administrator/components
[relname] => g:/joomla_1012/administrator/components
)
)
</source>

==Clean a path string==
Syntax:
<source lang=php>
JFolder::makeSafe($path);
</source>
Identically to the JFile::makeSafe() function. It cleans all odd characters out of the string and returns a clean path.

==Example==
Ok, and how does this look in actual code. We are going to read the contents of a folder called images. In it, al large number of files are placed. We want to create a subfolder, called jpg and filter all jpg files out and move them to the jpg subfolder. After that, we will move the complete subfolder to another place on the server.
<source lang=php>
<?php
//First we set up parameters
$searchpath = JPATH_COMPONENT . DS . "images";

//Then we create the subfolder called jpg
if ( !JFolder::create($searchpath . DS . "jpg") ) {
//Throw error message and stop script
}

//Now we read all jpg files and put them in an array.
$jpg_files = JFolder::files($searchpath, '.jpg');

//Now we need some stuff from the JFile:: class to move all files into the new folder
foreach ($jpg_files as $file) {
JFile::move($searchpath. DS . $file, $searchpath . DS. "jpg" . $file);
}

//Lastly, we are moving the complete subdir to the root of the component.
if (JFolder::move($searchpath . DS. "jpg", $JPATH_COMPONENT) ) {
//Redirect with perhaps a happy message
} else {
//Throw an error
}
?>
</source>

This is example script only, but gives a general idea of the possibilities. I did not touch other stuff like JError to keep it clean and simple.
<noinclude>[[Category:Development]]</noinclude>

API17:JFile

2012-07-01T08:54:49Z

BastianW: /* See also */ added crosslink to: How to use the filesystem package

__NOTOC__
=={{JVer|11.1}} JFile==
===Description===
{{Description:JFile}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JFile|Edit Descripton]]<nowiki>]</nowiki>
</span>
===Methods===
{| class="wikitable sortable"
|-
!Visibility
!Method name
!Description
|-
|public static
|[[JFile::copy/11.1|copy]]
|Copies a file.
|-
|public static
|[[JFile::delete/11.1|delete]]
|Delete a file or array of files.
|-
|public static
|[[JFile::exists/11.1|exists]]
|Wrapper for the standard file_exists function.
|-
|public static
|[[JFile::getExt/11.1|getExt]]
|Gets the extension of a file name.
|-
|public static
|[[JFile::getName/11.1|getName]]
|Returns the name, without any path.
|-
|public static
|[[JFile::makeSafe/11.1|makeSafe]]
|Makes file name safe to use.
|-
|public static
|[[JFile::move/11.1|move]]
|Moves a file.
|-
|public static
|[[JFile::read/11.1|read]]
|Read the contents of a file.
|-
|public static
|[[JFile::stripExt/11.1|stripExt]]
|Strips the last extension off a file name.
|-
|public static
|[[JFile::upload/11.1|upload]]
|Moves an uploaded file to a destination folder.
|-
|public static
|[[JFile::write/11.1|write]]
|Write contents to a file.
|-
|}
* '''Defined in''' libraries/joomla/filesystem/file.php
===Importing===
<source lang="php">jimport( 'joomla.filesystem.file' );</source>
===See also===
* {{JVer|11.1}} '''JFile source code''' on [[jplatform:filesystem/file.php|BitBucket]]
* {{JVer|11.1}} Subpackage [[Subpackage Filesystem/11.1|Filesystem]]
* [[JFile|Other versions of JFile]]
* [[How_to_use_the_filesystem_package|How to use the filesystem package]]
{{SeeAlso:JFile}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JFile|Edit See Also]]<nowiki>]</nowiki>
</span>

===User contributed notes===
<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=JFile
category=CodeExample
category=ClassExample
include=*
namespace=CodeExample
format= ,,,
</dpl>
<noinclude>[[Category:Platform]][[Category:Platform 11.1]][[Category:JFile]]</noinclude>

API17:JError

2012-07-01T07:47:55Z

BastianW: /* See also */ added crosslink to : "Display error messages and notices"

__NOTOC__
=={{JVer|11.1}} JError==
===Description===
{{Description:JError}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JError|Edit Descripton]]<nowiki>]</nowiki>
</span>
===Note===
JError is deprecated use PHP exceptions instead

===Methods===
{| class="wikitable sortable"
|-
!Visibility
!Method name
!Description
|-
|public static
|[[JError::addToStack/11.1|addToStack]]
|Method to add non-JError thrown JExceptions to the stack for debugging purposes.
|-
|public static
|[[JError::attachHandler/11.1|attachHandler]]
|Method that attaches the error handler to .
|-
|public static
|[[JError::customErrorHandler/11.1|customErrorHandler]]
|
|-
|public static
|[[JError::customErrorPage/11.1|customErrorPage]]
|Display a custom error page and exit gracefully.
|-
|public static
|[[JError::detachHandler/11.1|detachHandler]]
|Method that detaches the error handler from .
|-
|public static
|[[JError::getError/11.1|getError]]
|Method for retrieving the last exception object in the error stack.
|-
|public static
|[[JError::getErrorHandling/11.1|getErrorHandling]]
|Method to get the current error handler settings for a specified error level.
|-
|public static
|[[JError::getErrors/11.1|getErrors]]
|Method for retrieving the exception stack.
|-
|public static
|[[JError::handleCallback/11.1|handleCallback]]
|Callback error handler

|-
|public static
|[[JError::handleDie/11.1|handleDie]]
|Die error handler

|-
|public static
|[[JError::handleEcho/11.1|handleEcho]]
|Echo error handler

|-
|public static
|[[JError::handleIgnore/11.1|handleIgnore]]
|Ignore error handler

|-
|public static
|[[JError::handleLog/11.1|handleLog]]
|Log error handler

|-
|public static
|[[JError::handleMessage/11.1|handleMessage]]
|Message error handler

|-
|public static
|[[JError::handleVerbose/11.1|handleVerbose]]
|Verbose error handler

|-
|public static
|[[JError::isError/11.1|isError]]
|Method to determine if a value is an exception object.
|-
|public static
|[[JError::raise/11.1|raise]]
|Create a new object given the passed arguments.
|-
|public static
|[[JError::raiseError/11.1|raiseError]]
|Wrapper method for the method with predefined error level of E_ERROR and backtrace set to true.
|-
|public static
|[[JError::raiseNotice/11.1|raiseNotice]]
|Wrapper method for the method with predefined error level of E_NOTICE and backtrace set to false.
|-
|public static
|[[JError::raiseWarning/11.1|raiseWarning]]
|Wrapper method for the method with predefined error level of E_WARNING and backtrace set to false.
|-
|public static
|[[JError::registerErrorLevel/11.1|registerErrorLevel]]
|Method to register a new error level for handling errors.
|-
|public static
|[[JError::renderBacktrace/11.1|renderBacktrace]]
|
|-
|public static
|[[JError::setErrorHandling/11.1|setErrorHandling]]
|Method to set the way the will handle different error levels.
|-
|public static
|[[JError::throwError/11.1|throwError]]
|
|-
|public static
|[[JError::translateErrorLevel/11.1|translateErrorLevel]]
|Translate an error level integer to a human readable string e.g.
|-
|}
* '''Defined in''' libraries/joomla/error/error.php
===Importing===
<source lang="php">jimport( 'joomla.error.error' );</source>
===See also===
* {{JVer|11.1}} '''JError source code''' on [[jplatform:error/error.php|BitBucket]]
* {{JVer|11.1}} Subpackage [[Subpackage Error/11.1|Error]]
* [[JError|Other versions of JError]]
* [[Display_error_messages_and_notices|Display error messages and notices]]
{{SeeAlso:JError}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JError|Edit See Also]]<nowiki>]</nowiki>
</span>
===User contributed notes===

API17:JRequest::getInt

2012-07-01T07:26:43Z

BastianW: /* User contributed notes */ added example

__NOTOC__
=={{JVer|11.1}} JRequest::getInt==
===Description===
Fetches and returns a given filtered variable.

{{Description:JRequest::getInt}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JRequest::getInt|Edit Descripton]]<nowiki>]</nowiki>
</span>
<source lang="php">
public static function getInt (
$name
$default=0
$hash= 'default'
)
</source>
{| class="wikitable"
|-
!Parameter
!Type
!Default
!Description
|-
|$name
|
|
|
|-
|$default
|
|0
|
|-
|$hash
|
|'default'
|
|-
|}
* '''Returns'''
* '''Defined''' on line 175 of libraries/joomla/environment/request.php
* '''Referenced by'''
** [[JModuleHelper::_load/11.1|JModuleHelper::_load]]
** [[JHtmlTabs::_loadBehavior/11.1|JHtmlTabs::_loadBehavior]]
** [[JHtmlSliders::_loadBehavior/11.1|JHtmlSliders::_loadBehavior]]
** [[JControllerForm::cancel/11.1|JControllerForm::cancel]]
** [[JControllerForm::edit/11.1|JControllerForm::edit]]
** [[JFormFieldRules::getInput/11.1|JFormFieldRules::getInput]]
** [[JModelAdmin::populateState/11.1|JModelAdmin::populateState]]
** [[JControllerForm::save/11.1|JControllerForm::save]]
===See also===
* {{JVer|11.1}} '''JRequest::getInt source code''' on [[jplatform:environment/request.php#cl-167|BitBucket]]
* {{JVer|11.1}} Class [[JRequest/11.1|JRequest]]
* {{JVer|11.1}} Subpackage [[Subpackage_Environment/11.1|Environment]]
* [[JRequest::getInt|Other versions of JRequest::getInt]]
{{SeeAlso:JRequest::getInt}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JRequest::getInt|Edit See Also]]<nowiki>]</nowiki>
</span>
===User contributed notes===
===Example===
<source lang="php">
$ourresult = JRequest::getInt( 'inputbox', 0, 'post' );
</source>

<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=JRequest::getInt
category=CodeExample
category=MethodExample
include=*
namespace=CodeExample
format= ,,,
</dpl>
<noinclude>[[Category:JRequest]][[Category:JRequest::getInt]]</noinclude>

API17:JRequest::getBool

2012-07-01T07:25:44Z

BastianW: /* User contributed notes */ added example

__NOTOC__
=={{JVer|11.1}} JRequest::getBool==
===Description===
Fetches and returns a given filtered variable.

{{Description:JRequest::getBool}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JRequest::getBool|Edit Descripton]]<nowiki>]</nowiki>
</span>
<source lang="php">
public static function getBool (
$name
$default=false
$hash= 'default'
)
</source>
{| class="wikitable"
|-
!Parameter
!Type
!Default
!Description
|-
|$name
|
|
|
|-
|$default
|
|false
|
|-
|$hash
|
|'default'
|
|-
|}
* '''Returns'''
* '''Defined''' on line 213 of libraries/joomla/environment/request.php
* '''Referenced by'''
** [[JModuleHelper::getModules/11.1|JModuleHelper::getModules]]
** [[JModuleHelper::renderModule/11.1|JModuleHelper::renderModule]]
===See also===
* {{JVer|11.1}} '''JRequest::getBool source code''' on [[jplatform:environment/request.php#cl-205|BitBucket]]
* {{JVer|11.1}} Class [[JRequest/11.1|JRequest]]
* {{JVer|11.1}} Subpackage [[Subpackage_Environment/11.1|Environment]]
* [[JRequest::getBool|Other versions of JRequest::getBool]]
{{SeeAlso:JRequest::getBool}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JRequest::getBool|Edit See Also]]<nowiki>]</nowiki>
</span>
===User contributed notes===
===Example===
<source lang="php">
$ourresult = JRequest::getBool( 'inputcheckbox', false, 'post' );
</source>

<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=JRequest::getBool
category=CodeExample
category=MethodExample
include=*
namespace=CodeExample
format= ,,,
</dpl>
<noinclude>[[Category:JRequest]][[Category:JRequest::getBool]]</noinclude>

API17:JRequest

2012-07-01T07:14:32Z

BastianW: /* See also */ added link to "Retrieving and Filtering GET and POST requests with JRequest::getVar"

__NOTOC__
=={{JVer|11.1}} JRequest==
===Description===
{{Description:JRequest}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JRequest|Edit Descripton]]<nowiki>]</nowiki>
</span>
===Note===
JRequest is deprecated get the [[JInput/11.1]] object from the application instead
===Methods===
{| class="wikitable sortable"
|-
!Visibility
!Method name
!Description
|-
|public static
|[[JRequest::_cleanArray/11.1|_cleanArray]]
|Adds an array to the GLOBALS array and checks that the GLOBALS variable is not being attacked.
|-
|public static
|[[JRequest::_cleanVar/11.1|_cleanVar]]
|Clean up an input variable.
|-
|public static
|[[JRequest::checkToken/11.1|checkToken]]
|Checks for a form token in the request.
|-
|public static
|[[JRequest::clean/11.1|clean]]
|Cleans the request from script injection.
|-
|public static
|[[JRequest::get/11.1|get]]
|Fetches and returns a request array.
|-
|public static
|[[JRequest::getBool/11.1|getBool]]
|Fetches and returns a given filtered variable.
|-
|public static
|[[JRequest::getCmd/11.1|getCmd]]
|Fetches and returns a given filtered variable.
|-
|public static
|[[JRequest::getFloat/11.1|getFloat]]
|Fetches and returns a given filtered variable.
|-
|public static
|[[JRequest::getInt/11.1|getInt]]
|Fetches and returns a given filtered variable.
|-
|public static
|[[JRequest::getMethod/11.1|getMethod]]
|Gets the request method.
|-
|public static
|[[JRequest::getString/11.1|getString]]
|Fetches and returns a given filtered variable.
|-
|public static
|[[JRequest::getURI/11.1|getURI]]
|Gets the full request path.
|-
|public static
|[[JRequest::getVar/11.1|getVar]]
|Fetches and returns a given variable.
|-
|public static
|[[JRequest::getWord/11.1|getWord]]
|Fetches and returns a given filtered variable.
|-
|public static
|[[JRequest::set/11.1|set]]
|Sets a request variable.
|-
|public static
|[[JRequest::setVar/11.1|setVar]]
|Set a variabe in one of the request variables.
|-
|protected static
|[[JRequest::_stripSlashesRecursive/11.1|_stripSlashesRecursive]]
|Strips slashes recursively on an array.
|-
|}
* '''Defined in''' libraries/joomla/environment/request.php
===Importing===
<source lang="php">jimport( 'joomla.environment.request' );</source>
===See also===
* {{JVer|11.1}} '''JRequest source code''' on [[jplatform:environment/request.php|BitBucket]]
* {{JVer|11.1}} Subpackage [[Subpackage Environment/11.1|Environment]]
* [[JRequest|Other versions of JRequest]]
* [[Retrieving_and_Filtering_GET_and_POST_requests_with_JRequest::getVar|Retrieving and Filtering GET and POST requests with JRequest::getVar]]
{{SeeAlso:JRequest}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JRequest|Edit See Also]]<nowiki>]</nowiki>
</span>

===User contributed notes===
<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=JRequest
category=CodeExample
category=ClassExample
include=*
namespace=CodeExample
format= ,,,
</dpl>
<noinclude>[[Category:Platform]][[Category:Platform 11.1]][[Category:JRequest]]</noinclude>

J1.5:Creating a search plugin

2012-06-29T21:40:19Z

BastianW: /* Coding examples */ added joomla 1.5 version tag

{{review}}
==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.

{{JVer|1.5}}
<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>

{{JVer|2.5}}
<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

{{JVer|1.5}}
<source lang="xml"><install version="1.5" type="plugin" group="search"></source>

{{JVer|2.5}}
<source lang="xml">
<extension version="2.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:
<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; shown 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

{{JVer|1.5}}
<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.

{{JVer|2.5}}
<source lang="xml">
<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>
</source>

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

{{JVer|1.5}}
<source lang="xml"></install></source>

{{JVer|2.5}}
<source lang="xml"></extension></source>

==PHP file==
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
//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;
}</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">
$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)==
{{JVer|1.5}}{{JVer|1.6}}{{JVer|2.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:
<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 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:
<source lang="INI">
SEARCH LIMIT=Zoek limiet
NUMBER OF SEARCH ITEMS TO RETURN=Aantal weer te geven zoekresultaten</source>

==Coding examples==
==Joomla 1.5==
{{JVer|1.5}}
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==
*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

[[Category:Tutorials]]
[[Category:Plugin Development]]

J1.5:Creating a search plugin

2012-06-29T21:38:22Z

BastianW: /* Quick tips */

{{review}}
==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.

{{JVer|1.5}}
<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>

{{JVer|2.5}}
<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

{{JVer|1.5}}
<source lang="xml"><install version="1.5" type="plugin" group="search"></source>

{{JVer|2.5}}
<source lang="xml">
<extension version="2.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:
<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; shown 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

{{JVer|1.5}}
<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.

{{JVer|2.5}}
<source lang="xml">
<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>
</source>

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

{{JVer|1.5}}
<source lang="xml"></install></source>

{{JVer|2.5}}
<source lang="xml"></extension></source>

==PHP file==
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
//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;
}</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">
$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)==
{{JVer|1.5}}{{JVer|1.6}}{{JVer|2.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:
<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 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:
<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. 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 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

[[Category:Tutorials]]
[[Category:Plugin Development]]

J1.5:Creating a search plugin

2012-06-29T21:37:10Z

BastianW: /* INI file(s) */ added version tags

{{review}}
==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.

{{JVer|1.5}}
<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>

{{JVer|2.5}}
<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

{{JVer|1.5}}
<source lang="xml"><install version="1.5" type="plugin" group="search"></source>

{{JVer|2.5}}
<source lang="xml">
<extension version="2.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:
<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; shown 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

{{JVer|1.5}}
<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.

{{JVer|2.5}}
<source lang="xml">
<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>
</source>

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

{{JVer|1.5}}
<source lang="xml"></install></source>

{{JVer|2.5}}
<source lang="xml"></extension></source>

==PHP file==
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
//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;
}</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">
$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)==
{{JVer|1.5}}{{JVer|1.6}}{{JVer|2.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:
<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 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:
<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. 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 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

[[Category:Tutorials]]
[[Category:Plugin Development]]

J1.5:Creating a search plugin

2012-06-29T21:33:42Z

BastianW: /* XML file */ updated section with joomla 2.5 infos

{{review}}
==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.

{{JVer|1.5}}
<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>

{{JVer|2.5}}
<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

{{JVer|1.5}}
<source lang="xml"><install version="1.5" type="plugin" group="search"></source>

{{JVer|2.5}}
<source lang="xml">
<extension version="2.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:
<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; shown 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

{{JVer|1.5}}
<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.

{{JVer|2.5}}
<source lang="xml">
<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>
</source>

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

{{JVer|1.5}}
<source lang="xml"></install></source>

{{JVer|2.5}}
<source lang="xml"></extension></source>

==PHP file==
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
//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;
}</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">
$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 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:
<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. 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 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

[[Category:Tutorials]]
[[Category:Plugin Development]]

J1.5:How to add breadcrumbs

2012-06-28T17:55:04Z

BastianW: /* Example */

Breadcrumbs are nice way to display the connection from the root. It gives you a hierarchical representation with click able links so that user can visit upper links easily. Breadcrumbs can be added in templates by using the object returned by $mainframe->getPathWay(). The member function addItem() allows to add a breadcrumb with the title of choice.

There are two parameters used for breadcrumbs creation process, and the first parameter is the title for the breadcrumb and the second parameter is the URL. If we do not need the breadcrumb to work like a link then we need to simply pass a blank string and then it will not work like a click able URL. This term is useful for hierarchical components where we have subcategories: we can generate a link to each and then end with the title of the current record or category.

The JPathway is currently used by the breadcrumbs module. If you are adding a new component and have already configured breadcrumbs, you may need to go into the breadcrumbs configuration and add the menu item for you component to the selection on the menu selelist.

== Example ==
{{JVer|1.5}}{{JVer|1.6}}This example was written for Joomla 1.5, however the differences to Joomla 1.6 are minor.
A view's view.php could look something like this.
<pre>
class exampleViewdefault extends JView {
function display($tpl = null) {

$mainframe = &JFactory::getApplication();
$document = &JFactory::getDocument();
$pathway =& $mainframe->getPathway();

JHTML::_('behavior.modal');
$model =& $this->getModel();
$data = $model->getData();

$this->assignRef( 'events', $data);

$document->setTitle( $this->events['name'] );
$pathway->addItem($this->events['name'], '');

parent::display($tpl);

}
}
</pre>

{{JVer|2.5}} The display function from a view's view.php for joomla 2.5 could look something like this.
<pre>
public function display($tpl = null)
{

$app = JFactory::getApplication();
$pathway = $app->getPathway();
$pathway->addItem('My Added Breadcrumb Link', 'http://www.yourdomain.tld');

parent::display($tpl);

}
</pre>

== See Also==
* http://docs.joomla.org/JPathway
* http://api.joomla.org/1.5/Joomla-Framework/Application/JPathway.html
* http://api.joomla.org/11.4/Joomla-Platform/Application/JPathway.html
* http://docs.joomla.org/API16:JPathway

[[Category:Tutorials]][[Category:Component Development]]

J1.5:How to add breadcrumbs

2012-06-28T17:50:36Z

BastianW: added joomla 2.5 example

Breadcrumbs are nice way to display the connection from the root. It gives you a hierarchical representation with click able links so that user can visit upper links easily. Breadcrumbs can be added in templates by using the object returned by $mainframe->getPathWay(). The member function addItem() allows to add a breadcrumb with the title of choice.

There are two parameters used for breadcrumbs creation process, and the first parameter is the title for the breadcrumb and the second parameter is the URL. If we do not need the breadcrumb to work like a link then we need to simply pass a blank string and then it will not work like a click able URL. This term is useful for hierarchical components where we have subcategories: we can generate a link to each and then end with the title of the current record or category.

The JPathway is currently used by the breadcrumbs module. If you are adding a new component and have already configured breadcrumbs, you may need to go into the breadcrumbs configuration and add the menu item for you component to the selection on the menu selelist.

== Example ==
{{JVer|1.5}}{{JVer|1.6}}This example was written for Joomla 1.5, however the differences to Joomla 1.6 are minor.
A view's view.php could look something like this.
<pre>
class exampleViewdefault extends JView {
function display($tpl = null) {

$mainframe = &JFactory::getApplication();
$document = &JFactory::getDocument();
$pathway =& $mainframe->getPathway();

JHTML::_('behavior.modal');
$model =& $this->getModel();
$data = $model->getData();

$this->assignRef( 'events', $data);

$document->setTitle( $this->events['name'] );
$pathway->addItem($this->events['name'], '');

parent::display($tpl);

}
}
</pre>

{{JVer|2.5}} The display function from a view's view.php for joomla 2.5 could look something like this.
<pre>
public function display($tpl = null)
{

$app = JFactory::getApplication();
$this->state = $this->get('State');
$this->item = $this->get('Item');

$pathway = $app->getPathway();
$pathway->addItem('My Added Breadcrumb Link', 'http://www.yourdomain.tld');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode("\n", $errors));
return false;
}

$this->_prepareDocument();
parent::display($tpl);

}
</pre>

== See Also==
* http://docs.joomla.org/JPathway
* http://api.joomla.org/1.5/Joomla-Framework/Application/JPathway.html
* http://api.joomla.org/11.4/Joomla-Platform/Application/JPathway.html
* http://docs.joomla.org/API16:JPathway

[[Category:Tutorials]][[Category:Component Development]]

J1.5:How to add breadcrumbs

2012-06-28T17:34:11Z

BastianW: /* See Also */ added API16 Link

{{JVer|1.5}}{{JVer|1.6}}This tutorial was written for Joomla 1.5, however the differences to Joomla 1.6 are minor.

Breadcrumbs are nice way to display the connection from the root. It gives you a hierarchical representation with click able links so that user can visit upper links easily. Breadcrumbs can be added in templates by using the object returned by $mainframe->getPathWay(). The member function addItem() allows to add a breadcrumb with the title of choice.

There are two parameters used for breadcrumbs creation process, and the first parameter is the title for the breadcrumb and the second parameter is the URL. If we do not need the breadcrumb to work like a link then we need to simply pass a blank string and then it will not work like a click able URL. This term is useful for hierarchical components where we have subcategories: we can generate a link to each and then end with the title of the current record or category.

The JPathway is currently used by the breadcrumbs module. If you are adding a new component and have already configured breadcrumbs, you may need to go into the breadcrumbs configuration and add the menu item for you component to the selection on the menu selelist.

== Example ==
A view's view.php could look something like this.
<pre>
class exampleViewdefault extends JView {
function display($tpl = null) {

$mainframe = &JFactory::getApplication();
$document = &JFactory::getDocument();
$pathway =& $mainframe->getPathway();

JHTML::_('behavior.modal');
$model =& $this->getModel();
$data = $model->getData();

$this->assignRef( 'events', $data);

$document->setTitle( $this->events['name'] );
$pathway->addItem($this->events['name'], '');

parent::display($tpl);

}
}
</pre>

== See Also==
* http://docs.joomla.org/JPathway
* http://api.joomla.org/1.5/Joomla-Framework/Application/JPathway.html
* http://api.joomla.org/11.4/Joomla-Platform/Application/JPathway.html
* http://docs.joomla.org/API16:JPathway

[[Category:Tutorials]][[Category:Component Development]]

User:BastianW

2012-06-28T17:21:52Z

BastianW:

I´m a Joomla developer and in my spare free time I add some content to the Joomla Wiki ;-).

--------
Elements I often use (as a kind of notepad) ;-)

{{JVer|1.5}}
{{JVer|1.6}}
{{JVer|2.5}}

User:BastianW

2012-06-28T17:21:32Z

BastianW:

I´m a Joomla developer and in my spare free time I add some content to the Joomla Wiki ;-).

--------
Elements I often use (as a kind of notepad) ;-)

{{JVer|1.5}}
{{JVer|1.6}}

J1.5:How to add breadcrumbs

2012-06-28T17:20:29Z

BastianW: added information that this section is only for joomla 1.5/1.6

{{JVer|1.5}}{{JVer|1.6}}This tutorial was written for Joomla 1.5, however the differences to Joomla 1.6 are minor.

Breadcrumbs are nice way to display the connection from the root. It gives you a hierarchical representation with click able links so that user can visit upper links easily. Breadcrumbs can be added in templates by using the object returned by $mainframe->getPathWay(). The member function addItem() allows to add a breadcrumb with the title of choice.

There are two parameters used for breadcrumbs creation process, and the first parameter is the title for the breadcrumb and the second parameter is the URL. If we do not need the breadcrumb to work like a link then we need to simply pass a blank string and then it will not work like a click able URL. This term is useful for hierarchical components where we have subcategories: we can generate a link to each and then end with the title of the current record or category.

The JPathway is currently used by the breadcrumbs module. If you are adding a new component and have already configured breadcrumbs, you may need to go into the breadcrumbs configuration and add the menu item for you component to the selection on the menu selelist.

== Example ==
A view's view.php could look something like this.
<pre>
class exampleViewdefault extends JView {
function display($tpl = null) {

$mainframe = &JFactory::getApplication();
$document = &JFactory::getDocument();
$pathway =& $mainframe->getPathway();

JHTML::_('behavior.modal');
$model =& $this->getModel();
$data = $model->getData();

$this->assignRef( 'events', $data);

$document->setTitle( $this->events['name'] );
$pathway->addItem($this->events['name'], '');

parent::display($tpl);

}
}
</pre>

== See Also==
* http://docs.joomla.org/JPathway
* http://api.joomla.org/1.5/Joomla-Framework/Application/JPathway.html
* http://api.joomla.org/11.4/Joomla-Platform/Application/JPathway.html

[[Category:Tutorials]][[Category:Component Development]]

J1.5:How to add breadcrumbs

2012-06-28T17:14:41Z

BastianW: /* See Also */ Fixed URLs

Breadcrumbs are nice way to display the connection from the root. It gives you a hierarchical representation with click able links so that user can visit upper links easily. Breadcrumbs can be added in templates by using the object returned by $mainframe->getPathWay(). The member function addItem() allows to add a breadcrumb with the title of choice.

There are two parameters used for breadcrumbs creation process, and the first parameter is the title for the breadcrumb and the second parameter is the URL. If we do not need the breadcrumb to work like a link then we need to simply pass a blank string and then it will not work like a click able URL. This term is useful for hierarchical components where we have subcategories: we can generate a link to each and then end with the title of the current record or category.

The JPathway is currently used by the breadcrumbs module. If you are adding a new component and have already configured breadcrumbs, you may need to go into the breadcrumbs configuration and add the menu item for you component to the selection on the menu selelist.

== Example ==
A view's view.php could look something like this.
<pre>
class exampleViewdefault extends JView {
function display($tpl = null) {

$mainframe = &JFactory::getApplication();
$document = &JFactory::getDocument();
$pathway =& $mainframe->getPathway();

JHTML::_('behavior.modal');
$model =& $this->getModel();
$data = $model->getData();

$this->assignRef( 'events', $data);

$document->setTitle( $this->events['name'] );
$pathway->addItem($this->events['name'], '');

parent::display($tpl);

}
}
</pre>

== See Also==
* http://docs.joomla.org/JPathway
* http://api.joomla.org/1.5/Joomla-Framework/Application/JPathway.html
* http://api.joomla.org/11.4/Joomla-Platform/Application/JPathway.html

[[Category:Tutorials]][[Category:Component Development]]

API17:JDatabase::loadObjectList

2012-06-26T21:33:01Z

BastianW: addes small example

__NOTOC__
=={{JVer|11.1}} JDatabase::loadObjectList==
===Description===
Method to get an array of the result set rows from the database query where each row is an object.

{{Description:JDatabase::loadObjectList}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JDatabase::loadObjectList|Edit Descripton]]<nowiki>]</nowiki>
</span>
<source lang="php">
public function loadObjectList (
$key=''
$class= 'stdClass'
)
</source>
{| class="wikitable"
|-
!Parameter
!Type
!Default
!Description
|-
|$key
|
|''
|
|-
|$class
|
|'stdClass'
|
|-
|}
* '''Returns'''
* '''Defined''' on line 707 of libraries/joomla/database/database.php
===See also===
* {{JVer|11.1}} '''JDatabase::loadObjectList source code''' on [[jplatform:database/database.php#cl-699|BitBucket]]
* {{JVer|11.1}} Class [[JDatabase/11.1|JDatabase]]
* {{JVer|11.1}} Subpackage [[Subpackage_Database/11.1|Database]]
* [[JDatabase::loadObjectList|Other versions of JDatabase::loadObjectList]]
{{SeeAlso:JDatabase::loadObjectList}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JDatabase::loadObjectList|Edit See Also]]<nowiki>]</nowiki>
</span>
===User contributed notes===

===Examples===

<source lang="php">
// Create a new query object.
$db = &JFactory::getDBO();
$query = $db->getQuery(true);
$query->select('cats.description AS description, cats.title AS titel');
$query->from('#__categories AS cats');
$query->where('cats.id="1"');
$db->setQuery($query);
$Category = $db->loadObjectList();
</source>

<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=JDatabase::loadObjectList
category=CodeExample
category=MethodExample
include=*
namespace=CodeExample
format= ,,,
</dpl>
<noinclude>[[Category:JDatabase]][[Category:JDatabase::loadObjectList]]</noinclude>

API17:JApplication::enqueueMessage

2012-06-23T06:59:35Z

BastianW: /* Examples */ added frontent example

__NOTOC__
=={{JVer|11.1}} JApplication::enqueueMessage==
===Description===
Enqueue a system message.

{{Description:JApplication::enqueueMessage}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JApplication::enqueueMessage|Edit Descripton]]<nowiki>]</nowiki>
</span>
<source lang="php">
public function enqueueMessage (
$msg
$type= 'message'
)
</source>
{| class="wikitable"
|-
!Parameter
!Type
!Default
!Description
|-
|$msg
|string
|
|The message to enqueue.
|-
|$type
|string
|'message'
|The message type.
|-
|}
* '''Returns''' void
* '''Defined''' on line 390 of libraries/joomla/application/application.php
* '''Since''' {{JVer|11.1 }}
===See also===
* {{JVer|11.1}} '''JApplication::enqueueMessage source code''' on [[jplatform:application/application.php#cl-382|BitBucket]]
* {{JVer|11.1}} Class [[JApplication/11.1|JApplication]]
* {{JVer|11.1}} Subpackage [[Subpackage_Application/11.1|Application]]
* [[JApplication::enqueueMessage|Other versions of JApplication::enqueueMessage]]
{{SeeAlso:JApplication::enqueueMessage}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JApplication::enqueueMessage|Edit See Also]]<nowiki>]</nowiki>
</span>
===Examples===

To enqueue a message (in a module) for a administration/backend component:
<source lang="php">
$this->_mainframe->enqueueMessage('YOUR MESSAGE GOES HERE', 'message');
</source>

To enqueue a message (in a module) for a website/frontent component:
<source lang="php">
JFactory::getApplication()->enqueueMessage('YOUR MESSAGE GOES HERE', 'message');
</source>

===User contributed notes===
<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=JApplication::enqueueMessage
category=CodeExample
category=MethodExample
include=*
namespace=CodeExample
format= ,,,
</dpl>
<noinclude>[[Category:JApplication]][[Category:JApplication::enqueueMessage]]</noinclude>

API17:JApplication::enqueueMessage

2012-06-23T06:48:02Z

BastianW: Added "Examples"

__NOTOC__
=={{JVer|11.1}} JApplication::enqueueMessage==
===Description===
Enqueue a system message.

{{Description:JApplication::enqueueMessage}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JApplication::enqueueMessage|Edit Descripton]]<nowiki>]</nowiki>
</span>
<source lang="php">
public function enqueueMessage (
$msg
$type= 'message'
)
</source>
{| class="wikitable"
|-
!Parameter
!Type
!Default
!Description
|-
|$msg
|string
|
|The message to enqueue.
|-
|$type
|string
|'message'
|The message type.
|-
|}
* '''Returns''' void
* '''Defined''' on line 390 of libraries/joomla/application/application.php
* '''Since''' {{JVer|11.1 }}
===See also===
* {{JVer|11.1}} '''JApplication::enqueueMessage source code''' on [[jplatform:application/application.php#cl-382|BitBucket]]
* {{JVer|11.1}} Class [[JApplication/11.1|JApplication]]
* {{JVer|11.1}} Subpackage [[Subpackage_Application/11.1|Application]]
* [[JApplication::enqueueMessage|Other versions of JApplication::enqueueMessage]]
{{SeeAlso:JApplication::enqueueMessage}}
<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JApplication::enqueueMessage|Edit See Also]]<nowiki>]</nowiki>
</span>
===Examples===

To enqueue a message (in the module) for a administration/backend component:
<source lang="php">
$this->_mainframe->enqueueMessage('LoremImpsum');
</source>

===User contributed notes===
<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=JApplication::enqueueMessage
category=CodeExample
category=MethodExample
include=*
namespace=CodeExample
format= ,,,
</dpl>
<noinclude>[[Category:JApplication]][[Category:JApplication::enqueueMessage]]</noinclude>

User:BastianW

2012-06-22T20:42:19Z

BastianW: Created page with "I´m a Joomla developer and in my spare free time I add some content to the Joomla Wiki ;-)."

I´m a Joomla developer and in my spare free time I add some content to the Joomla Wiki ;-).

API16:JDatabaseQuery/order

2012-06-22T20:39:08Z

BastianW: /* Examples */ Added a small order example

<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Description:JDatabaseQuery/order|Edit Descripton]]<nowiki>]</nowiki>
</span>

{{Description:JDatabaseQuery/order}}

===Syntax===
<source lang="php">order($columns)</source>

{| class="wikitable"
|-
!Parameter Name
!Default Value
!Description
|-
| $columns
|
| A string or array of ordering columns
|}

===Defined in===
libraries/joomla/database/databasequery.php
===Importing===
<source lang="php">jimport( 'joomla.database.databasequery' );</source>

===Source Body===
<source lang="php">
public function order($columns)
{
if (is_null($this->_order)) {
$this->_order = new JDatabaseQueryElement('ORDER BY', $columns);
} else {
$this->_order->append($columns);
}

return $this;
}
</source>

<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[SeeAlso:JDatabaseQuery/order|Edit See Also]]<nowiki>]</nowiki>
</span>
{{SeeAlso:JDatabaseQuery/order}}

===Examples===
<CodeExamplesForm />
<source lang="php">
$query->from('`#__categories` AS a');
$query->where('a.extension = "com_weblinks" and a.published = "1"');
$query->order('a.title ASC');
</source>

<dpl>
noresultsheader=\n
category=order
category=JDatabaseQuery
category=CodeExample
category=MethodExample
include=*
format= ,,,
</dpl>