Joomla! Documentation - User contributions [en]

Making single installation packages for Joomla! 1.5 and 2.5 series

2011-11-29T20:25:27Z

Creuzerm: /* Obsolte code */ Spelling correction

{{review}}

It is possible to create a single installation package which can install a component in Joomla! 1.5, 1.6 and 1.7 with minor changes. Below you will find some of the most common tricks required to create an extension which is compatible with all current versions of the Joomla! CMS.

== Dealing with API changes ==
You will regularly bump into cases where an API has changed between Joomla! 1.5, 1.6 and 1.7. In order to cater for them, you need to run slightly different code based on the Joomla! version. Right now it's possible to do that by writing conditional statements like this:

<source lang="php">
if(version_compare(JVERSION,'1.7.0','ge')) {
// Joomla! 1.7 code here
} elseif(version_compare(JVERSION,'1.6.0','ge')) {
// Joomla! 1.6 code here
} else {
// Joomla! 1.5 code here
}
</source>

If you do not have Joomla! 1.7-specific code -i.e it is the same as the Joomla! 1.6-specific code- please use the following code:

<source lang="php">
if(version_compare(JVERSION,'1.6.0','ge')) {
// Joomla! 1.6 code here
} else {
// Joomla! 1.5 code here
}
</source>

While this conditional statement looks like an overkill, it has two major advantages:
* Compatibility with all Joomla! versions using the same package, therefore using the same codebase, ergo less maintenance overhead
* Once, let's say, Joomla! 1.8 is released and you decide to drop support for earlier Joomla! releases, we can just search your code for "if(version_compare(JVERSION," and remove all of the legacy code.

== One XML configuration file, multiple Joomla! versions ==

Various XML files in Joomla! accept settings, or parameters. For example your extension manifest file, the config.xml file and the view XML files all accept such settings. You may have noticed that whereas in Joomla! 1.5 these were found under the <params> tags, in Joomla! 1.6 and later they are found inside <filedsets>. One hidden secret of Joomla! is that Joomla! 1.5 will ignore Joomla! 1.6 syntax, whereas Joomla! 1.6/1.7 will ignore Joomla! 1.5 syntax. This allows you to have a single XML file which caters for all Joomla! releases. For example, here's a sample config.xml file, to be placed in the component's backend directory:

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

<params>
<param name="foobar" type="text" default="" size="30"
label="COM_FOOBAR_OPTION_FOOBAR_LBL"
description ="COM_FOOBAR_OPTION_FOOBAR_DESC" />
</params>


<fieldset
name="basic"
label="COM_FOOBAR_OPTIONS_SECTION_BASIC_LBL"
description="COM_FOOBAR_OPTIONS_SECTION_BASIC_DESC"
>
<field name="foobar" type="text" default="" size="30"
label="COM_FOOBAR_OPTION_FOOBAR_LBL"
description ="COM_FOOBAR_OPTION_FOOBAR_DESC" />
</fieldset>
</config>
</source>

That's how easy it is!

== Dealing with languages ==

=== How to load component-local translation files in Joomla! 1.5 ===

Joomla! 1.6 introduced a new feature where a user can place language files inside the component's directory, e.g. administrator/com_foobar/language/en-GB/en-GB.com_foobar.ini, in order to provide language overrides. But Joomla! 1.5 doesn't support this feature. Or does it? Even though it can not do that automatically, you can do so in your extension's dispatcher file, e.g. administrator/com_foobar/foobar.php. Here's the magic code to do that in the backend:
<source lang="php">
$jlang =& JFactory::getLanguage();
$jlang->load('com_foobar', JPATH_ADMINISTRATOR, null, true);
$jlang->load('com_foobar', JPATH_COMPONENT_ADMINISTRATOR, null, true);
</source>
and the frontend:
<source lang="php">
$jlang =& JFactory::getLanguage();
$jlang->load('com_foobar', JPATH_SITE, null, true);
$jlang->load('com_foobar', JPATH_COMPONENT, null, true);
</source>

=== Tips and tricks for language strings ===

All your translation keys should consist of uppercase characters without spaces (that is A-Z, 0-9 and underscores). All translation values should be included in double quotation marks. This allows the translation files to be parsed by Joomla! 1.5/1.6/1.7 alike. You are also suggested to prefix your translation keys with the extension's name, albeit this is not required. For example, this is a good translation string:
COM_FOOBAR_CPANEL_TITLE="Foobar Control Panel"
whereas this is a '''bad''' translation string:
CONTROL PANEL=Foobar Control Panel
The former works with all current versions of Joomla!, the latter doesn't.

If you have double quotation marks in your translation values, please replace them with single quotation marks. While Joomla! 1.5 allowed escaping the double quotation marks with \", Joomla! 1.6 under newer versions of PHP don't and require you to escape them as "__QQ__" which throws off Joomla! 1.5's parser. The workaround is to take advantage of a little known fact about HTML, that attributes can be wrapped in single quotation marks. For instance, change this:
COM_FOOBAR_SOME_KEY=<a href="http://www.example.com">Just a test</a>
to this:
COM_FOOBAR_SOME_KEY="<a href='http://www.example.com'>Just a test</a>"
It is valid HTML, it works on Joomla! 1.5/1.6/1.7 but it will invalidates XHTML. You can't always win, sorry.

=== Making untranslated strings look more beautiful ===

The problem with using tight translation keys as we described is that untranslated strings now look something like COM_FOOBAR_VIEWNAME_SOMEKEY. If you have volunteer translators you can bet your head that most translations will not be in sync with your component and you will have untranslated strings. In Joomla! 1.5, using "natural language" keys, you got to show your users the default (English) text if a translation key didn't exist in their language. This is impossible in Joomla! 1.6... or maybe not?

We can use the same little trick in our component's dispatcher as with our component-local translation loading string above. Here's how to load the English translation file in the backend of your component, then overwrite only the keys which exist with the user's selected language, essentially allowing untranslated keys to show in English:

<source lang="php">
$jlang =& JFactory::getLanguage();
$jlang->load('com_foobar', JPATH_ADMINISTRATOR, 'en-GB', true);
$jlang->load('com_foobar', JPATH_ADMINISTRATOR, null, true);
</source>

The same thing in the front-end:

<source lang="php">
$jlang =& JFactory::getLanguage();
$jlang->load('com_foobar', JPATH_SITE, 'en-GB', true);
$jlang->load('com_foobar', JPATH_SITE, null, true);
</source>

== JElement vs JFormField ==

Oh, the struggle! You need a custom widget in the configuration section of your component. In Joomla! 1.5 you could just create a new JElement. In Joomla! 1.6 you could just create a new JFormField. But both? In a single file? You can employ a simple trick. In the following example I am going to create a rather lame element, called SQL2, which displays a multi-selection box out of the results of a SQL statement. This is made as part of a fictitious module called mod_foobar

First, let your configuration know where to load the custom widget files from, by putting this in your module's XML manifest file:

<source lang="xml">
<params addpath="/modules/mod_foobar/elements">
<param name="ids" type="sql2" default=""
label="MOD_FOOBAR_LEVELS_TITLE"
description="MOD_FOOBAR_LEVELS_DESC"
query="SELECT `foobar_level_id`, `title` FROM `#__foobar_levels`"
key_field="foobar_level_id"
value_field="title" />
</params>

<config addfieldpath="/modules/mod_foobar/elements">
<fields name="params">
<fieldset name="basic">
<field name="ids" type="sql2" default=""
label="MOD_FOOBAR_LEVELS_TITLE"
description="MOD_FOOBAR_LEVELS_DESC"
query="SELECT `foobar_level_id`, `title` FROM `#__foobar_levels`"
key_field="foobar_level_id"
value_field="title" />
</fieldset>
</fields>
</config>
</source>

As you see, we instruct both Joomla! 1.5 and 1.6/1.7 to look into the same directory, for the same-named file (sql2.php). Here are the contents of the modules/mod_foobar/elements/sql2.php file:

<source lang="php">
defined('_JEXEC') or die('Restricted Access');

/*
* This trick allows us to extend the correct class, based on whether it's Joomla! 1.5 or 1.6
*/
if(!class_exists('JFakeElementBase')) {
if(version_compare(JVERSION,'1.6.0','ge')) {
class JFakeElementBase extends JFormField {
// This line is required to keep Joomla! 1.6/1.7 from complaining
public function getInput() {}
}
} else {
class JFakeElementBase extends JElement {}
}
}

/**
* Our main element class, creating a multi-select list out of an SQL statement
*/
class JFakeElementSQL2 extends JFakeElementBase
{
var $_name = 'SQL2';

// Joomla! 1.5
function fetchElement($name, $value, &$node, $control_name)
{
$db = & JFactory::getDBO();
$db->setQuery($node->attributes('query'));
$key = ($node->attributes('key_field') ? $node->attributes('key_field') : 'value');
$val = ($node->attributes('value_field') ? $node->attributes('value_field') : $name);
return JHTML::_('select.genericlist', $db->loadObjectList(), ''.$control_name.'['.$name.'][]', 'class="inputbox" multiple="multiple" size="5"', $key, $val, $value, $control_name.$name);
}

// Joomla! 1.6
function getInput()
{
$db = & JFactory::getDBO();
$db->setQuery($this->element['query']);
$key = ($this->element['key_field'] ? $this->element['key_field'] : 'value');
$val = ($this->element['value_field'] ? $this->element['value_field'] : $this->name);
return JHTML::_('select.genericlist', $db->loadObjectList(), $this->name, 'class="inputbox" multiple="multiple" size="5"', $key, $val, $this->value, $this->id);
}
}

/*
* Part two of our trick; we define the proper element name, depending on whether it's Joomla! 1.5 or 1.6
*/
if(version_compare(JVERSION,'1.6.0','ge')) {
class JFormFieldSQL2 extends JFakeElementSQL2 {}
} else {
class JElementSQL2 extends JFakeElementSQL2 {}
}
</source>

Considering that most custom widgets have a lot more code than this, you can create two different initialisation sections for Joomla! 1.5 and 1.6/1.7 (fetchElement and getInput), populate class variables, then call a big, common method to render the bulk of the widget (just like we did with JHTML's genericlist in the example above). This will eliminate the need to rewrite the same code over again just to cater for a new Joomla! version.

== Obsolete code ==

Joomla 1.6 / 1.7 have been left any code obsolete, we should review code for do compatible with all versions.
=== Global Mainframe ===
Bad: <source>global $mainframe;</source>
Good: <source>$mainframe = &JFactory::getApplication();</source>

=== Global Option ===
Bad: <source>global $option;</source>
Good: <source>$option = JRequest::getCmd('option');</source>

I will add more changes like it.

== Content plugins work slightly different ==

The content plugins in Joomla! 1.5 were using the onPrepareContent method, whereas the content plugins in Joomla! 1.6/1.7 use the onContentPrepare method. The arguments have also changed. You can, however, create a single content plugin which runs on both Joomla! versions without rewriting code. Here's how:

<source lang="php">
defined('_JEXEC') or die();

jimport('joomla.plugin.plugin');

class plgContentFoobar extends JPlugin
{
public function onPrepareContent( &$article, &$params, $limitstart = 0 )
{
$article->text = $this->doSomethingWith($article->text);
}

public function onContentPrepare($context, &$row, &$params, $page = 0)
{
// Danger, Will Robinson! $row in Joomla! 1.6/1.7 may be a string, not an article object!
if(is_object($row)) {
return $this->onPrepareContent($row, $params, $page);
} else {
$row = $this->doSomethingWith($row);
}

return true;
}

private function doSomethingWith($text)
{
// Apparently, you have to do something here ;)
return $text;
}
}
</source>

== Updating doesn't work as you'd expect ==

There is a small but very disturbing bug in Joomla! 1.6. Updating a component whose manifest XML states version="1.5.0" doesn't allow you to run the SQL statements. Namely, the SQL files you specify under the "<install><sql>" tags won't run. You can neither use the new "<update>" tag. You are stuck with no way to run SQL commands on component update!

The ugly workaround is to create a file named script.foobar.php with the following contents:

<source lang="php">
<?php
define('_JEXEC') or die();

class Com_FoobarInstallerScript {

function update($parent) {
$db = JFactory::getDBO();
// Obviously you may have to change the path and name if your installation SQL file ;)
if(method_exists($parent, 'extension_root')) {
$sqlfile = $parent->getPath('extension_root').DS.'install.sql';
} else {
$sqlfile = $parent->getParent()->getPath('extension_root').DS.'install.sql';
}
// Don't modify below this line
$buffer = file_get_contents($sqlfile);
if ($buffer !== false) {
jimport('joomla.installer.helper');
$queries = JInstallerHelper::splitSql($buffer);
if (count($queries) != 0) {
foreach ($queries as $query)
{
$query = trim($query);
if ($query != '' && $query{0} != '#') {
$db->setQuery($query);
if (!$db->query()) {
JError::raiseWarning(1, JText::sprintf('JLIB_INSTALLER_ERROR_SQL_ERROR', $db->stderr(true)));
return false;
}
}
}
}
}
}
</source>

Reference that file in the end of your manifest XML file, just above the closing install tag, with:
<source type="xml">
<scriptfile>script.foobar.php</scriptfile>
</source>

This will force Joomla! 1.6 to run your extension's installation SQL file during the component update, just like Joomla! 1.5 used to do. Enjoy!

== Menu item creation tricks ==

===For Joomla! 1.5===

You have to add a line similar to the following in your component's manifest XML file, inside the <code><administration><code> tag.

<source lang="xml">
<menu view="yourview" img="../media/com_example/logo-16.png">COM_EXAMPLE</menu>
</source>
or
<source lang="xml">
<menu view="yourview" img="../media/com_example/logo-16.png">Example Component</menu>
</source>

In both cases, you need to create a file named en-GB.com_example.menu.ini in administrator/languages/en-GB (you can use the manifest's <code><languages></code> tag to copy it during installation). In the first case (using a translation key), its contents should be:
<source>
COM_EXAMPLE=Example Component
</source>
In the second case (using natural language strings) its contents should be
<source>
Example Component=Example Component
</source>

NB: Joomla! 1.5 sorts the Component menu items based on the key you supply in your XML manifest. If you use the COM_EXAMPLE approach, your component will be sorted with all the components beginning with "C", e.g. just before Contacts on a fresh Joomla! 1.5 installation, no matter what the translation is! This leads to funny results, especially with non-English languages where the translated component names do not follow the same sorting order as their English names. If you are bilingual or multilingual, I think you know what I mean…

===For Joomla! 1.6 and later versions===

You have to add a line similar to the following in your component's manifest XML file, inside the <code><administration></code> tag.
<source lang="xml">
<menu view="yourview" img="../media/com_example/logo-16.png">COM_EXAMPLE</menu>
</source>

You can not use a natural language string. Doing so will result in your component name appearing as example-component in the menu and you will be unable to provide a translation.

You need to create a file named en-GB.com_example.sys.ini in administrator/languages/en-GB (you can use the manifest's <code><languages></code> tag to copy it during installation) or in administrator/components/com_example/language/en-GB. In the latter case, you must not include the translation file in the <code><languages></code> tag. As long as you have placed the language directory in your <code><files></code> tag, it will be copied along when the component is being installed.

The contents of that file should be:
<source>
COM_EXAMPLE="Example Component"
</source>

Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards.

NB: Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu for the majority (non-English speaking!) of Joomla! users.

===How to have a cross-version (Joomla! 1.5, 1.6 and later) component===

If your component is supposed to be installed under both Joomla! 1.5 and Joomla! 1.6/1.7/2.5, you can do a little trick. You have to add a line similar to the following in your component's manifest XML file, inside the <code><administration></code> tag.
<source lang="xml">
<menu view="yourview" img="../media/com_example/logo-16.png">COM_EXAMPLE</menu>
</source>

Now, you need to create two files, one for Joomla! 1.5 and one for Joomla! 1.6. For Joomla! 1.5 you need to create a file named en-GB.com_example.menu.ini in administrator/languages/en-GB (you can use the manifest's <code><languages></code> tag to copy it during installation). Its contents should be:
<source>
COM_EXAMPLE=Example Component
</source>
For Joomla! 1.6 you need to create a file named en-GB.com_example.sys.ini in administrator/languages/en-GB (you can use the manifest's <code><languages></code> tag to copy it during installation) or in administrator/components/com_example/language/en-GB. In the latter case, you must not include the translation file in the <code><languages></code> tag. As long as you have placed the language directory in your <code><files></code> tag, it will be copied along when the component is being installed.

The contents of that file should be:
<source>
COM_EXAMPLE="Example Component"
</source>

The only drawback is that your component will appear as weirdly sorted in the Components menu of Joomla! 1.5. Given the very near expiration date of Joomla! 1.5 (April 2012) this is not a major drawback and experience shows that users don't really care that much.

===What if you do that and nothing happens?===

Joomla! is supposed to create the components menu entries afresh every time you re-install the component. If this doesn't happen in your case, try uninstalling and re-installing your component. If you're not sure if Joomla! has the correct Components menu item translation key, you can always check the menu items database table. This will prevent you from unnecessary frustration when your translation files don't work simply because Joomla! has the wrong translation key in the table.

== More tricks? ==

I am sure that by writing this page I have left out a number of tricks which I am already using in my software. If you get stuck somewhere, feel free to take a look at how I've implemented things in Admin Tools Core, Akeeba Backup Core and Akeeba Release System, my Joomla! 1.5/1.6/1.7 compatible extensions. If you find a better way to implement something, or found a trick not listed here, feel free to edit this wiki page. Sharing the knowledge is caring!

Peace, love and friendship,

Nicholas K. Dionysopoulos, AkeebaBackup.com Lead Developer

Accessing the database using JDatabase

2010-01-22T16:23:11Z

Creuzerm: /* Insert Query Execution */ Add link to more documentation

J1.5:Using the JToolBar class in the frontend

2010-01-19T17:25:16Z

Creuzerm: Spelling Correction

Anyone whom has used the very useful JToolbarHelper class in an administration component has probably already realised that there is nothing quite so useful for the frontend. The good news is that we can create our own very simply using the JToolbar class.

First lets create the helper class. I tend to make a different helper class for each component as they will each have a different toolbar. I like to keep all my helpers in the administration end as they can often be used for both sides of the component. So firstly create a helpers directory in your component.

/administrator/components/com_yourcom/helpers

and create a file called toolbar.php

The following is an example of a very simple toolbar helper class. Copy and paste this into your toolbar.php file. Don't forget to change 'yourcom' to the name of your component. Notice also that we've included the Jtoolbar class at the top of the file.
<source lang="php">
// no direct access
defined('_JEXEC') or die('Restricted access');
jimport('joomla.html.toolbar');

class YourcomHelperToolbar extends JObject
{
function getToolbar() {

$bar =& new JToolBar( 'My Toolbar' );
$bar->appendButton( 'Standard', 'new', 'New Record', 'new', false );
$bar->appendButton( 'Separator' );
$bar->appendButton( 'Standard', 'delete', 'Delete Record', 'delete', false );

return $bar->render();

}

}

</source>
Lets look at this code. When the 'getToolbar' function is called it creates a new instance of the JToolbar class.
<source lang="php">
$bar =& new JToolBar( 'Associations Toolbar' );

</source>
We can then add buttons to this object.
<source lang="php">
$bar->appendButton( 'Standard', 'new', 'New Record', 'new', false );

</source>
The first parameter is the button type. have a look a the JToolbar or JButton docs for a full list of these.

The second parameter is the class to apply to the button ( this will help us to apply an image to it as in the backend )

The third parameter is the text to display on the button.

The fourth is the task to set. When the button is pressed the javascript submitButton function is called and the hidden field 'task' is set to this value. We will see this later in our template file.

The fifth states whether a selection must be made from an admin list before continuing.

we then simply return our bar object.

We now have a choice of where to render this bar object. You can create it in a view and apply it to a template if you wish. I personally prefer to render it in the entry point file. In this example this would be yourcom.php and would look something like this. Notice that we have also included our helper file here.
<source lang="php">
// no direct access
defined('_JEXEC') or die('Restricted access');

// Require the base controller
require_once (JPATH_COMPONENT.DS.'controller.php');

// Require specific controller if requested
if($controller = JRequest::getVar('controller')) {
require_once (JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php');
}

// Component Helper
jimport('joomla.application.component.helper');

// Load the toolbar helper
require_once( JPATH_COMPONENT_ADMINISTRATOR.DS.'helpers'.DS.'toolbar.php' );

// render the toolbar on the page. rendering it here means that it is displayed on every view of your component.
echo YourcomHelperToolbar::getToolbar();

// Create the controller
$classname = 'YourcomController'.$controller;
$controller = new $classname( );

// Perform the Request task
$controller->execute( JRequest::getVar('task'));

// Redirect if set by the controller
$controller->redirect();

</source>

Having created this the toolbar you created should render on the page but there are a few more things we need to do to make it work. We need to ensure that every view template page has an admin form for the submitButton function to work.
<source lang="php">
<form action = "index.php" method = "post" id = "adminForm" name = "adminForm" />

<input type = "hidden" name = "task" value = "" />
<input type = "hidden" name = "option" value = "com_yourcom" />
</form>

</source>
Now when one of the buttons is clicked the submitbutton function will set the hidden field 'task' to the task identifier you specified in the toolbar class.
<source lang="php">
$bar->appendButton( 'Standard', 'delete', 'Delete Record', 'new', false );

</source>
In the above button the task would be 'new' ( the fourth parameter );

If this task is going to be run we had better make sure that it's available in our controller. Open up your controller.php and add the following.
<source lang="php">
function new()
{
JRequest::setVar('view' , 'new');

parent::display();
}

</source>
This will display your 'new' view assuming you've already created one. You could put any code in here you like.

There we go that should create a nice easy to use toolbar class. There is one last thing though. You may have noticed that the icons are not displaying as they do in the backend. To make this work we have to 'steal' some images and some CSS from the backend.

open up the folder

administrator/templates/khepri/images

and copy the directory 'toolbar' directory to your frontend templates/rhuk_milkyway/images folder

It should now look like this

templates/rhuk_milkyway/images/toolbar

and be filled with png images

Now you could hunt around through the backend css to find the correct code to display the buttons but I've saved you the trouble. In your templates/css folder create a file called icon.css and paste in the following code.
<source lang="php">
/* toolbar */
div.toolbar { float: right; text-align: right; padding: 0; }

table.toolbar { border-collapse: collapse; padding: 0; margin: 0; }
table.toolbar td { padding: 1px 1px 1px 4px; text-align: center; color: #666; height: 48px; }
table.toolbar td.spacer { width: 10px; }
table.toolbar td.divider { border-right: 1px solid #eee; width: 5px; }

table.toolbar span { float: none; width: 32px; height: 32px; margin: 0 auto; display: block; }

table.toolbar a {
display: block; float: left;
white-space: nowrap;
border: 1px solid #fbfbfb;
padding: 1px 5px;
cursor: pointer;
}

table.toolbar a:hover {
border-left: 1px solid #eee;
border-top: 1px solid #eee;
border-right: 1px solid #ccc;
border-bottom: 1px solid #ccc;
text-decoration: none;
color: #0B55C4;
}

/** toolbar icons **/
.icon-32-send { background-image: url(../images/toolbar/icon-32-send.png); }
.icon-32-delete { background-image: url(../images/toolbar/icon-32-delete.png); }
.icon-32-help { background-image: url(../images/toolbar/icon-32-help.png); }
.icon-32-cancel { background-image: url(../images/toolbar/icon-32-cancel.png); }
.icon-32-config { background-image: url(../images/toolbar/icon-32-config.png); }
.icon-32-apply { background-image: url(../images/toolbar/icon-32-apply.png); }
.icon-32-back { background-image: url(../images/toolbar/icon-32-back.png); }
.icon-32-forward { background-image: url(../images/toolbar/icon-32-forward.png); }
.icon-32-save { background-image: url(../images/toolbar/icon-32-save.png); }
.icon-32-edit { background-image: url(../images/toolbar/icon-32-edit.png); }
.icon-32-copy { background-image: url(../images/toolbar/icon-32-copy.png); }
.icon-32-move { background-image: url(../images/toolbar/icon-32-move.png); }
.icon-32-new { background-image: url(../images/toolbar/icon-32-new.png); }
.icon-32-upload { background-image: url(../images/toolbar/icon-32-upload.png); }
.icon-32-assign { background-image: url(../images/toolbar/icon-32-publish.png); }
.icon-32-html { background-image: url(../images/toolbar/icon-32-html.png); }
.icon-32-css { background-image: url(../images/toolbar/icon-32-css.png); }
.icon-32-menus { background-image: url(../images/toolbar/icon-32-menu.png); }
.icon-32-publish { background-image: url(../images/toolbar/icon-32-publish.png); }
.icon-32-unpublish { background-image: url(../images/toolbar/icon-32-unpublish.png);}
.icon-32-restore { background-image: url(../images/toolbar/icon-32-revert.png); }
.icon-32-trash { background-image: url(../images/toolbar/icon-32-trash.png); }
.icon-32-archive { background-image: url(../images/toolbar/icon-32-archive.png); }
.icon-32-unarchive { background-image: url(../images/toolbar/icon-32-unarchive.png); }
.icon-32-preview { background-image: url(../images/toolbar/icon-32-preview.png); }
.icon-32-default { background-image: url(../images/toolbar/icon-32-default.png); }

</source>
We now have to include this css in to your template so add the following line to the top of your template index.php
<source lang="php">
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/rhuk_milkyway/css/icon.css" type="text/css" />

</source>
(if you are using the toolbar on a component that other people will be installing it would be better to use:
<source lang="php">
$mainframe->addCustomHeadTag ('<link rel="stylesheet" href="'.$this->baseurl.'/components/com_**yourcomponent**/filename.css" type="text/css" media="screen" />');

</source>
And finally - you will require the javascript file used in the backend to enable the buttons to work ;-)
<source lang="php">
$mainframe->addCustomHeadTag ('<script type="text/javascript" src="/includes/js/joomla.javascript.js"></script>');

</source>
And that's it. your toolbar should now render exactly as it does in the backend. This is a very simple toolbar helper. You could equally copy the JToolbarHelper class exactly in to your toolbar helper and use the functions in the same way as the backend. This would allow you to reuse your jtoolbar helper in multiple components.
<noinclude>[[Category:Development]]</noinclude>

J1.5:How to add tooltips to your Joomla! website

2009-12-09T21:48:58Z

Creuzerm: /* Customizing Your Yooltips */

{{review}}
===Tooltips Overview===
A tooltips is a piece of text that pops up when you hover the mouse over a region on a website. If you use the Joomla! back end, for example, tooltips are used to help explain the action of different parameters, as shown in the screenshot below:

[[Image:Screen_tooltip_example_20090208.png]]

Tooltips are a great way to give the user access to information without using up space on the screen. You can use basic tooltips just by adding a "title" attribute to a tag. However, this doesn't give you the option to style the tooltips. With Joomla! version 1.5, it is very easy to add styled tooltips to your site. This tutorial will show you how. <blockquote>''Note: If you are converting old code, make sure it doesn't use the prototype.js file. That file will keep the tooltips from working.''</blockquote>

===Activate Tooltip Behavior===
To start, you must activate the tooltip behavior. This is done with the following line of code:
<source lang="php">
JHTML::_('behavior.tooltip');
</source>
Note that you only put this line in once per file. A good place is right after the <code>defined('_JEXEC') or die('Restricted access');</code> line. If you are curious about what this line does, it inserts the following JavaScript code in the heading of the HTML page:
<source lang="html4strict">
<script type="text/javascript">
window.addEvent('domready', function(){
var JTooltips = new Tips($$('.hasTip'),
{ maxTitleChars: 50, fixed: false});
});
</script>
</source>
This allows tooltips to function, as outlined below.

===Create a Tooltip with the JHTML::tooltip Method===
One way to create a tooltip is using the JHTML::tooltip method. The API documentation is available at [http://api.joomla.org/Joomla-Framework/HTML/JHTML.html#tooltip http://api.joomla.org/Joomla-Framework/HTML/JHTML.html#tooltip]. The method definition is shown below.
<source lang="php">
void tooltip (string $tooltip, [string $title = ''], [string $image = 'tooltip.png'],
[string $text = ''], [string $href = ''], [boolean $link = 1])
</source>
The brackets mean the parameter is optional. The first parameter, "$tooltip", is the only required parameter. The equals specifies the default if you do not pass that parameter. For example, the image file 'tooltip.png' is the default image.

The following is a basic tooltip. Keep in mind that the image variable must be in reference to 'includes/js/ThemeOffice'. Use the prefix '../../../' to reference from the root of the Joomla installation.
<source lang="php">
JHTML::tooltip('This is the tooltip text', 'Tooltip title', 'tooltip.png', '',
'http://www.joomla.org');
</source>
The above will make a tooltip using the default "tooltip.png" image, as shown below.[[Image:Tooltip_tutorial_example_screenshot_20090208.png|center|frame]]Clicking the image will take you to <tt>http://www.joola.org</tt>, since that is the "$href" argument. The HTML source for this tooltip is as follows:
<source lang="html4strict">
<span class="editlinktip hasTip" title="Tooltip title::This is the tooltip text" >
<a href="http://www.joomla.org">
<img src="/my_joomla_path/includes/js/ThemeOffice/tooltip.png" border="0" alt="Tooltip"/></a>
</span>
</source>

<blockquote>''Internet Explorer Bug: As shown above, when you use the JHTML::tooltip method to create an image tooltip, it creates an "alt" attribute with the value "Tooltip". The "alt" attribute is used in cases where the image file cannot be found or for accessibility (for example, for blind users). Internet Explorer automatically -- and incorrectly -- displays the "alt" attribute as a tooltip. This means that image tooltips created by JHTML::tooltip (like the example above) will display with two tooltips when viewed with Internet Explorer, as shown below.''</blockquote>
[[Image:Tooltip_tutorial_ie7bug_20090301.png|center|frame]]
<blockquote>''You can avoid this problem either by using text tooltips or by not using this method for image tooltips. Instead, just enter the HTML manually and set the "alt" attribute to an empty string (alt="").''</blockquote>

This code is almost the same as above except the image will not be a link (because the "$href" argument is omitted).
<source lang="php">
JHTML::tooltip('This is the tooltip text', 'Tooltip title',
'tooltip.png', '', '', false);
</source>

A tooltip can be attached to an image or to text. For example, this code
<source lang="php">
echo JHTML::tooltip('This is a tooltip attached to text', 'Text Tooltip Title',
'', 'Hover on this text to see the tooltip');
</source>
will show a tooltip attached to text, as shown below.

[[Image:Tooltip_tutorial_example_screenshot2_20090208.png|center|frame]]

Note that specifying the "$text" parameter will override any image you have passed to tooltip.

===Create a Tooltip Using a CSS Class Name===
If we look at the HTML page source generated by the <code>JHTML::tooltip</code> function above, here is what we see:
<source lang="html4strict">
<span class="editlinktip hasTip"
title="Text Tooltip Title::This is a tooltip attached to text"
style="text-decoration: none; color: #333;">
Hover on this text to see the tooltip</span>
</source>
This function generates an HTML "span" tag with the classes "editlinktip" and "hasTip" and an attribute called "title". Notice that the the "title" attribute has two parts, <code><tooltip title>::<tooltip text></code> (for example, "Tooltip Title::This is the tooltip text"). You can create a tooltip with only text or with only a title. The title has implications for styling, as we'll see below.

The Javascript inserted by the <code>JHTML::('behavior_tooltip')</code> command we entered earlier picks up this tag based on the class called "hasTip". So, a second way of creating a tooltip is to simply create a tag with a class called "hasTip" and an attribute of "title". For example, this code
<source lang="html4strict">
<span class="hasTip"
title="Text Tooltip Title::This is a tooltip attached to text">
Hover on this text to see the tooltip</span>
</source>
will produce exactly the same effect as the <code>JHTML::tooltip()</code> example above.

===Adding CSS Styling to the Tooltip===
The default tooltips, whether using the JHTML::tooltip method or class method, use the following three CSS classes: <tt>.tool-tip</tt>, <tt>.tool-title</tt>, and <tt>.tool-text</tt>.

Here are the default styles.
<source lang="css">
/* Tooltips */
.tool-tip {
float: left;
background: #ffc;
border: 1px solid #D4D5AA;
padding: 5px;
max-width: 200px;
}

.tool-title {
padding: 0;
margin: 0;
font-size: 100%;
font-weight: bold;
margin-top: -15px;
padding-top: 15px;
padding-bottom: 5px;
background: url(../images/selector-arrow.png) no-repeat;
}

.tool-text {
font-size: 100%;
margin: 0;
}
</source>

If you have a custom CSS file, copy this code and alter it to your liking. Note that the <tt>.tool-title</tt> class uses by default the "selector-arrow.png" image. This is what gives the outline of the tooltip the little pointer in the upper left of the tooltip box. If you leave out a title in your tooltip, you will just get a rectangle, without the pointer.

===Customizing Your Tooltips===
Ok, now it's time to have some fun. The <code>JHTML::_('behavior.tooltip')</code> can take two optional parameters. The first parameter is the name of the CSS class that will be used to identify the tooltip. As we saw earlier, this defaults to "hasTip". The second optional parameter is an array of parameters that you can use to fine-tune the tooltip functionality. These are explained below.
* '''maxTitleChars:''' The maximum length of the title (the part of the "title" attribute before the "::")
* '''showDelay, hideDelay:''' The time to delay showing or hiding the tooltip, in milliseconds. Default is 100.
* '''className:''' The first part of the class name used to style the actual tooltip. The default, as we saw, is "tool", and the full class names by default are "tool-tip", "tool-title', and "tool-text". So, for example, if we set this to "custom", we would style the classes "custom-tip", "custom-title", and "custom-text".
* '''fixed:''' Whether or not to have the tooltip move with the mouse. If set to "true", the tooltip will be centered below the text or image. If set to "false", the tooltip will move with the mouse. Default is "false".
* '''onShow, onHide:''' Functions to call for the onShow and onHide events. We'll see an example below where we can use these to create a fade-in and fade-out for the tooltip.

In the next section, we'll show how to use these parameters with some examples.

===Tooltip With Different Classes===
In this example, we will create a tooltip using different selector and tooltip styling classes. Why might we want to do this? One reason would be if we had different types of tooltips and we wanted to style them differently.

Here is the code to create the tooltip Javascript function:
<source lang="php">
$toolTipArray = array('className'=>'custom2');
JHTML::_('behavior.tooltip', '.hasTip2', $toolTipArray);
</source>
In this code, we are creating an array with just one element -- to set the "className" parameter to "custom2". This means that, to style these tooltips, we would use the classes <tt>custom2-tip</tt>, <tt>custom2-title</tt>, and <tt>custom2-text</tt>. Then we call the method with the arguments ".hasTip2" and the array "$toolTipArray". It can be a little confusing, because we have two CSS classes at work here. The class ".hasTip2" is used in the HTML tag. That is how the Javascript program identifies the tooltips to operate on. The class "custom2" is used as the first part of the three CSS classes to use to style the actual tooltip itself.

To use this new tooltip, we could use the following code:
<source lang="html4strict">
<span class="hasTip2"
title="My Tooltip Title :: Tooltip text for hasTip2 class with custom2 style classes.">
hasTip2 and custom2 example</span>
</source>
Since we set the class to "hasTip2", this tag will be processed by the new version of the tooltip program. So, if we use both the default tooltip ("hasTip" class) and the new tooltip ("hasTip2" class) in the same page, we can style them differently using "tool-" styles for the default and "custom2-" styles for the "hasTip2" tooltips.

Next, let's look at a more complex example, shown below.
<source lang="php">
$toolTipArray = array('className' => 'custom2', 'showDelay'=>'500',
'hideDelay'=>'500', 'fixed'=>true,
'onShow'=>"function(tip) {tip.effect('opacity',
{duration: 500, wait: false}).start(0,1)}",
'onHide'=>"function(tip) {tip.effect('opacity',
{duration: 500, wait: false}).start(1,0)}");
JHTML::_('behavior.tooltip', '.hasTip2', $toolTipArray); ?>
</source>
Again, we are building an array to pass to the <code>JHTML::_('behavior.tooltip')</code> function. Again, we are setting the "className" parameter to "custom2". We are also setting the "showDelay" and "hideDelay" parameters to 500 milliseconds (.5 seconds). So the tooltip will show only after the mouse has hovered for this amount of time.

Notice that we are setting the parameter "fixed" to "true" (without the quotes). This means that the tooltip will not move with the mouse. Instead, it will always show centered below the tooltip text or image.

Finally, the tricky part. We are creating functions to pass in to the "onShow" and "onHide" events. These functions cause the tooltip to fade in and fade out over the space of 500 milliseconds. This is done by gradually varying the tooltip's CSS "opacity" style from "0" (completely transparent) to "1" (completely opaque). If we wanted the tooltip to be partially transparent, we could change these to <code>start(0,.8)</code> and <code>start(.8,0)</code>.

These functions are similar to the sample code in the [http://demos111.mootools.net/Tips MooTools demo tutorial]. Click on the link called "js code" and look at the code for the "Tips2" demo. We have just taken the code from the initialize function and incorporated it into the "onShow" and "onHide" functions.

The last line of code above creates the actual Javascript code in our Joomla! document. If we show the page and view source, we see the following:
<source lang="javascript">
window.addEvent('domready', function(){
var JTooltips = new Tips($$('.hasTip2'), {
maxTitleChars: 50, showDelay: 500, hideDelay: 500, className: 'custom2',
fixed: true,
onShow: function(tip) {tip.effect('opacity', {duration: 500, wait: false}).start(0,1)},
onHide: function(tip) {tip.effect('opacity', {duration: 500, wait: false}).start(1,0)}
});
});
</source>
So we can see the effect of the parameters that we passed to the <code>JHTML::_('behavior.tooltip')</code> method.

'''offsets Parameter'''
<blockquote>''Note: The "offsets" parameter doesn't work in version 1.5.9 and earlier because of a bug. As of version 1.5.10 it should work as outlined below.''</blockquote>
You can control the x and y distance, in pixels, from the cursor to the tooltip using the "offsets" parameter. This parameter must be an array as shown in the example code below:
<source lang="php">
// set x (horizontal) distance to 20 pixels, y (vertical) distance to 30 pixels
$toolTipArray = array('offsets'=>array('x'=>20, 'y'=>30), 'maxtitlechars'=>40);
JHTML::_('behavior.tooltip', '.customOffset', $toolTipArray);
</source>

===Using an External Javascript File===
There are times when you might prefer to work with a separate Javascript file. This gives you complete flexibility to use all of the mootools capabilities. To do this:
# Create the separate Javascript file and save it somewhere in your Joomla! site (for example, "templates/<your template>/js/yourjsfile.js".
# Use the <code>JHTML::script</code> function to add this script to your document. For example:
<source lang="php">
$filename = 'testtooltip.js'; // this file is used for class="hasTip3" titles
$path = 'templates/rhuk_milkyway/js/'; // path to the file
// true means MooTools will load if it is not already loaded
JHTML::script($filename, $path, true);
</source>
This will load your script into the document and make sure that the MooTools library is available.

===Complete Code Example===
Here is an example that incorporates all of the elements discussed in this tutorial. So you can see the code in action, we will create an override of the "mod_stats" Module and add our test code there. We will use the rhuk_milkyway template.

To set up the template override, create a folder called "templates/rhuk_milkyway/html/mod_stats" and copy the file "modules/mod_stats/tmpl/default.php" to this new folder.

After line 2 of this file (<code>defined('_JEXEC') or die('Restricted access');</code>), insert the following:
<source lang="php">
JHTML::_('behavior.tooltip');
$toolTipArray = array('className' => 'custom2', 'showDelay'=>'500', 'hideDelay'=>'500',
'fixed'=>'true'
, 'onShow'=>"function(tip) {tip.effect('opacity',
{duration: 500, wait: false}).start(0,1)}"
, 'onHide'=>"function(tip) {tip.effect('opacity',
{duration: 500, wait: false}).start(1,0)}");
JHTML::_('behavior.tooltip', '.hasTip2', $toolTipArray); // class="hasTip2" titles
$filename = 'testtooltip.js'; // used for class="hasTip3" titles
$path = 'templates/rhuk_milkyway/js/';
JHTML::script($filename, $path, true); // MooTools will load if it is not already loaded
</source>
Here we are creating the Javascript functions we will need later. The first line is the simple default declaration that will use the ".hasTip" and "tool-" CSS classes.

The next 5 lines create the more customized function that includes the fade-in and fade-out. It uses the ".hasTip2" to create the tip and the classes starting with "custom2-" to style the tooltip.

The last 3 lines reference the external Javascript file, which will be created below. The class information will be contained in that file.

Now, time for some more coding. At the end of the "modules/mod_stats/tmpl/default.php" file, add the code shown below:
<source lang="php">
<h1>Tooltip Examples</h1>
<?php echo JHTML::tooltip('This is the tooltip text', 'Tooltip title',
'tooltip.png', '', 'http://www.joomla.org');?>
<br/><br/>
<?php echo JHTML::tooltip('This is a tooltip attached to text', 'Text Tooltip Title',
'', 'Hover on this text to see the tooltip');?>
<br/><br/>
<a class="hasTip" title="My Title::Tooltip on 'a' tag text using default 'hasTip' class"
href="http://www.joomla.org">Tooltip on a link example</a>
<br/><br/>
<span class="hasTip2"
title="My Tooltip Title :: Tooltip text for hasTip2 class with custom2 style classes.">
hasTip2 and custom2 example</span>
<br/><br/>
<span class="hasTip3"
title="hasTip3 Title::This is using class 'hasTip3' using external JS script.">
hasTip3 hover text</span>
<br/><br/>
</source>
The first two examples using the <code>JHTML::tooltip</code> function to create the tooltip HTML code.

The third example shows an "a" tag with a tooltip. This illustrates that you can put tooltips on most HTML tags, not just "span" tags. Again, it is using the "hasTip" class, so it will be controlled by the Javascript above called with the ".hasTip" argument and will be styled with the default "tool-" styles.

The fourth example shows a "span" tag using the "hasTip2" class. So it will be styled using the "custom2-" classes and will have the "showDelay" and "hideDelay" of 500 milliseconds and have "fixed" equal to "true" (so the tip will not move with the mouse). Also, it uses the special fade-in and fade-out effects.

The last example will use the Javascript code from the external file, shown below.

Now, some more coding. Create a JavaScript file called "testtooltip.js" and save it into the folder "templates/rhuk_milkyway/js":
<source lang="javascript">
window.addEvent('domready', function(){
//do your tips stuff in here...
var zoomTip = new Tips($$('.hasTip3'), {
className: 'custom3', //this is the prefix for the CSS class
offsets: {
'x': 20, //default is 16
'y': 30 //default is 16
},
initialize:function(){
this.fx = new Fx.Style(this.toolTip, 'opacity',
{duration: 1000, wait: false}).set(0);
},
onShow: function(toolTip) {
this.fx.start(0,.8);
},
onHide: function(toolTip) {
this.fx.start(.8,0);
}
});
});
</source>
This code will operate on the "hasTip3" class and will use style classes starting with "custom3-". We are setting the x distance (from the cursor to the tooltip) to 20 pixels and the y distance to 30 pixels. This also has the fade-in and fade-out functionality, but the final "opacity" value is set to .8, meaning that the tooltip will be slightly transparent.

Finally, add this to the end of your "templates/rhuk_milkyway/css/template.css" file:
<source lang="css">
.custom2-tip {
color: #000;
width: 130px;
z-index: 13000;
}

.custom2-title {
font-weight: bold;
font-size: 11px;
margin: 0;
color: #024A68;
padding: 8px 8px 4px;
background: #3CA0D0;
border-bottom: 1px solid #024A68;
}

.custom2-text {
font-size: 11px;
padding: 4px 8px 8px;
background: #63ADD0;
}

.custom3-tip {
color: #000;
width: 130px;
z-index: 13000;
}

.custom3-title {
font-weight: bold;
font-size: 11px;
margin: 0;
color: #3E4F14;
padding: 8px 8px 4px;
background: #C3DF7D;
border-bottom: 1px solid #B5CF74;
}

.custom3-text {
font-size: 11px;
padding: 4px 8px 8px;
background: #CFDFA7;
}
</source>
Here we are just adding different colors for the "custom2-" and "custom3-" styles so you can see the effect of the different tooltip code.

Notice that <tt>.custom2-title</tt> and <tt>.custom3-title</tt> classes do not have a background property. So these tooltips will be a box without the neat little arrow pointing at the mouse. If you wanted, you could create an image similar to "templates/system/images/selector-arrow.png" of the right color and add that as a background to these classes.

===Example Code Screenshots===
Here are some screenshots taken from the sample code above. The first screenshot shows the modified "mod_stats" modules with our sample code.
[[Image:Screen_tooltip_example2_20090210.png|center|frame]]
The screenshot below shows the fade-in effect for the ".hasTip2" tooltip. Notice also that the tooltip is centered below the text. This is the effect of setting "fixed" equal to "true".
[[Image:Screen_tooltip_example1_20090209.png|center|frame]]
The last screenshot shows the different styling for the ".hasTip3" tooltip, based on the "custom3-" CSS class styles.
[[Image:Screen_tooltip_example3_20090210.png|center|frame]]

===More Information===
More information about the topics covered in this tutorial is available at the links below. Note that Joomla! version 1.5 uses MooTools version 1.11. The current version of MooTools is 1.2.
* Joomla API - [http://api.joomla.org http://api.joomla.org]
* Documentation for 1.11 MooTools Tips: [http://docs111.mootools.net/Plugins/Tips.js http://docs111.mootools.net/Plugins/Tips.js]
* Mootools demos for version 1.11 - [http://demos111.mootools.net/Tips http://demos111.mootools.net/Tips]
* Mootools Website - [http://www.mootools.net/ http://www.mootools.net/]

[[Category:Development]]

J1.5:Creating a search plugin

2009-12-03T20:03:46Z

Creuzerm: /* PHP file */

{{review}}
[[Category:Development]]
[[Category:Plugins]]
==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.
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC
"-//Joomla! 1.5//DTD plugin 1.0//EN" "http://dev.joomla.org/xml/1.5/plugin-install.dtd"></source>
To define that the plugin has to be a search plugin, add this line:
<source lang="xml"><install version="1.5" type="plugin" group="search"></source>
The type will define it is a plugin, the group defines the Plugin is in the group of search plugins.

After that, add some information about yourself and the plugin, like this:
<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; showed 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:
<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.

And do not forget to end your XML file with the following tag:
<source lang="xml"></install></source>

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

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

//Now define the registerEvent and the language file. Replace 'nameofplugin' with the name of your plugin.
$mainframe->registerEvent( 'onSearch', 'plgSearchnameofplugin' );
$mainframe->registerEvent( 'onSearchAreas', 'plgSearchnameofpluginAreas' );

JPlugin::loadLanguage( 'plg_search_nameofplugin' );

//Then define a function to return an array of search areas. Replace 'nameofplugin' with the name of your plugin.
function &plgSearchnameofpluginAreas()
{
static $areas = array(
'nameofplugin' => 'Nameofplugin'
);
return $areas;
}

//Then the real function has to be created. The database connection should be made.
//The function will be closed with an } at the end of the file.
function plgSearchnameofplugin( $text, $phrase='', $ordering='', $areas=null )
{
$db =& JFactory::getDBO();
$user =& JFactory::getUser();

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

//It is time to define the parameters! First get the right plugin; 'search' (the group), 'nameofplugin'.
$plugin =& JPluginHelper::getPlugin('search', 'nameofplugin');

//Then load the parameters of the plugin..
$pluginParams = new JParameter( $plugin->params );

//And define the parameters. For example like this..
$limit = $pluginParams->def( 'nameofparameter', defaultsetting );

//Use the function trim to delete spaces in front of or at the back of the searching terms
$text = trim( $text );

//Return Array when nothing was filled 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 4 variables that get passed in, which 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 something 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 translaters.

When you want to make your search plugin available in more languages, first add them to the <languages> tag in the XML file. Then create the same INI file, and change the part after the =, 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, then 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 an semicolon (;) at the end of a row. This causes errors. Check this before you test your plugin.
*Make sure the parameters in the XML file are closed correctly. When you add options, for example, you need to close it with </param>.
*It is easy to test on a localhost when you are still busy with editing your plugin.
*When making a zip-file to test it, 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

J1.5:Creating a search plugin

2009-12-03T20:02:46Z

Creuzerm: /* PHP file */ Added alternative example of how to format the search results as the code isn't obvious as to what is needed.

{{review}}
[[Category:Development]]
[[Category:Plugins]]
==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.
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC
"-//Joomla! 1.5//DTD plugin 1.0//EN" "http://dev.joomla.org/xml/1.5/plugin-install.dtd"></source>
To define that the plugin has to be a search plugin, add this line:
<source lang="xml"><install version="1.5" type="plugin" group="search"></source>
The type will define it is a plugin, the group defines the Plugin is in the group of search plugins.

After that, add some information about yourself and the plugin, like this:
<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; showed 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:
<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.

And do not forget to end your XML file with the following tag:
<source lang="xml"></install></source>

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

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

//Now define the registerEvent and the language file. Replace 'nameofplugin' with the name of your plugin.
$mainframe->registerEvent( 'onSearch', 'plgSearchnameofplugin' );
$mainframe->registerEvent( 'onSearchAreas', 'plgSearchnameofpluginAreas' );

JPlugin::loadLanguage( 'plg_search_nameofplugin' );

//Then define a function to return an array of search areas. Replace 'nameofplugin' with the name of your plugin.
function &plgSearchnameofpluginAreas()
{
static $areas = array(
'nameofplugin' => 'Nameofplugin'
);
return $areas;
}

//Then the real function has to be created. The database connection should be made.
//The function will be closed with an } at the end of the file.
function plgSearchnameofplugin( $text, $phrase='', $ordering='', $areas=null )
{
$db =& JFactory::getDBO();
$user =& JFactory::getUser();

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

//It is time to define the parameters! First get the right plugin; 'search' (the group), 'nameofplugin'.
$plugin =& JPluginHelper::getPlugin('search', 'nameofplugin');

//Then load the parameters of the plugin..
$pluginParams = new JParameter( $plugin->params );

//And define the parameters. For example like this..
$limit = $pluginParams->def( 'nameofparameter', defaultsetting );

//Use the function trim to delete spaces in front of or at the back of the searching terms
$text = trim( $text );

//Return Array when nothing was filled 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 4 variables that get passed it, which are evident by their names and use in the code.
What's not obvious is what the function should return. An array of objects that the search tool uses to display the results. The results could alternatively have been assembled something like this.
<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 translaters.

When you want to make your search plugin available in more languages, first add them to the <languages> tag in the XML file. Then create the same INI file, and change the part after the =, 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, then 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 an semicolon (;) at the end of a row. This causes errors. Check this before you test your plugin.
*Make sure the parameters in the XML file are closed correctly. When you add options, for example, you need to close it with </param>.
*It is easy to test on a localhost when you are still busy with editing your plugin.
*When making a zip-file to test it, 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

Search Engine Friendly URLs

2009-12-02T21:21:00Z

Creuzerm: Added link to http://docs.joomla.org/Routing

'''Joomla Routes'''

Joomla routes are created by the JRouter class. This class looks in the component root of the component specified in the "option" portion of the query string and includes the router.php file in that component's root directory. It then calls one of two functions: one for creating the SEF link and one for interpreting the SEF link.

The JRouter class is overridden by the Joomla CMS in /includes/router.php. In this file the build and parse functions are overridden to properly build and parse the URLs for the Joomla CMS.

com_component/router.php

The router.php file should contain the following two functions:
* ContentBuildRoute - this builds the SEF url
** Parameters
*** $query - this is a named array containing the querystring variables
** Returns: an array of segments where each segment is separated by a '/' when later combined to create the actual link (the items in the array should not contain '/' characters)
* ContentParseRoute - this interprets an SEF url
** Parameters
*** $segments - this is an array that contains the segments of the url requested.
** Returns: a name => value array of the querystring variables that the link maps to

'''The SEF Plugin'''

The Joomla System SEF plugin inherits JPlugin and overrides the onAfterRender() function. In this function the body of the response that will be sent to the browser is retrieved using JResponse::getBody(). The body of the response is then searched for links containing "/index.php..." and replaces them with a correct SEF url by calling JRoute::_(url).

JRoute builds SEF URLs by instantiating a JRouter object and requesting that it build the correct link from the passed in URL.

'''Handling SEF URLs'''

By default the SEF URLs are handled by the the JRouterSite object (from /includes/router.php) and is called by a call to JApplication::route() in index.php. This call is made on the $mainframe variable which is actually an instance of JSite (from /includes/application.php).

JApplication::route() has a non-destructive result on the $_GET array. By this I mean that JApplication::route() sets variables in $_GET by calling JRequest::set() with the overwrite flag set to false. Thus if a variable name is returned from JRouter::route() that is already in $_GET then it will not put that value into $_GET. This allows for custom routing.

'''Custom Routing'''

Joomla allows you to create your own routing mechanism. In order to create this mechanism you must have a plugin that overrides the JPlugin::onAfterInitialise() function. This function then parses the URL and creates the needed variables in $_GET before the standard Joomla routing is done.

==See Also==
http://docs.joomla.org/Routing

J2.5:Supporting SEF URLs in your component

2009-11-30T22:41:52Z

Creuzerm: /* The Slug */ changed word hyphen to colon as dcoumentation is referencing the ':' symbol

{{incomplete}}
{{RightTOC}}
[[Category:Development]]

== Routing Overview ==

Joomla! 1.5 is capable of creating and parsing URLs in any format, including human readable URL's. Another improvement is that this still works even if Joomla! runs a server other than Apache with the mod_rewrite module.

A good example of this is the "Welcome to Joomla" article. The first link shown was generated without mod_rewrite, and the second link was generated with mod_rewrite:

* <code><nowiki>http://www.example.com/index.php/the-news/1-latest-news/1-welcome-to-joomla</nowiki></code>
* <code><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></code>

== Preparing Your Data for Routing ==

=== The Alias ===

The first step is the generation of the so called alias. The alias is used in the URL instead of the title (the title is the text you want to have in the url). The alias has to be URI safe, which means accented UTF8 characters are replaced by their ASCII7 equivalents, white spaces by hyphens, etc.

The alias can be defined by the user, but you should ensure that the above requirements for a URL safe alias are met. A good way to do so is to use the JTable::check() method during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport( 'joomla.filter.output' );
if(empty($this->alias)) {
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the JFilterOutput::stringURLSafe() method.

=== The Slug ===

Continuing with the same example, the "slug" - "1-welcome-to-joomla" has two parts. The first part is the article identifier (id) and the second is the alias. They are separated by a colon. These two elements were combined during the database query in the model:

<pre>$query = 'SELECT a.*,'.
' CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(\':\', a.id, a.alias) ELSE a.id END as slug,'.
[...];</pre>

After this step the slug is used instead of the id.

== Routing URL's ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <code>JRoute</code> has three parameters and its prototype is:

<pre>JRoute::_( $url, $xhtml = true, $ssl=0 );</pre>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<pre>JRoute::_( 'index.php?view=article&id='.$row->slug );</pre>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using JRoute is that the router now handles $option (the component name) and the $Itemid (the menu item ID). The component itself doesn’t have to know its name ($option) or the active menu item ($Itemid) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the router.php in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the router.php in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions In the router.php. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (view=categories), the second is a single category (view=category) and the third is a single article (view=article).

The file router.php should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your installation XML in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute( &$query )
{
$segments = array();
if(isset($query['view']))
{
$segments[] = $query['view'];
unset( $query['view'] );
}
if(isset($query['id']))
{
$segments[] = $query['id'];
unset( $query['id'] );
};
return $segments;
}

</source>

<code>JRouter</code> passes a $query array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <code>/components/com_magic/...</code> would use a prefix <code>magic</code> (all lower case).

The next function in the <code>router.php</code> parses the URL:

<source lang="php">
function [componentname]ParseRoute( $segments )
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first, the catid is second and the id is third in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. $vars should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <code>router.php</code> is a very simple way to generate sef URL's but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<code><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></code>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <code><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></code>
* When viewing a category: <code><nowiki>http://www.example.com/[menualias]/[category]</nowiki></code>
* When viewing the categories overview: <code><nowiki>http://www.example.com/[menualias]</nowiki></code>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_( 'index.php?view=article&catid='.$row->catslug .'&id='.$row->slug );
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_( 'index.php?view=category&id='.$row->catslug );
</source>

The corresponding <code>router.php</code>:

<source lang="php">

function [''Componentname'']BuildRoute(&$query)
{
$segments = array();
if(isset( $query['catid'] ))
{
$segments[] = $query['catid'];
unset( $query['catid'] );
};
if( isset($query['id']) )
{
$segments[] = $query['id'];
unset( $query['id'] );
};
unset( $query['view'] );
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [''Componentname'']ParseRoute($segments)
{
$vars = array();
$menu =& JMenu::getInstance();
$item =& $menu->getActive();
// Count segments
$count = count( $segments );
//Handle View and Identifier
switch( $item->query['view'] )
{
case 'categories':
if($count == 1) {
$vars['view'] = 'category';
}
if($count == 2) {
$vars['view'] = 'article';
}
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count( $segments );
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article .
* The menu item is a link to the categories view and the $segments array has one item ($id). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the $segments array is the identifier for an article .

The result of all this code is nice and human readable component URL's.

== Application Route Parsing ==

The [[API Execution Order]] outlines that the route (URL) is parsed immediately after initialisation is complete. Since fancy URL's are not treated (yet) in the Administrator, we will follow the route parsing process in detail when <code>JSite::route</code> in the <code>index.php</code> file.

* Call to <code>JApplication::route</code>
** Clone the URI
** Call to <code>JApplication::getRouter</code>
*** Call to <code>JRouter::getInstance</code> passing the type ("site")
** Call to <code>JRouterSite::parse</code> passing the URI
*** Strip the suffix if applicable (added to $vars['format'])
*** Re-set the route (URI)
*** Call to <code>JRouter::parse</code> passing the URI
**** Call to <code>JRouterSite::_processParseRules</code> passing the URI (this will call custom route rules)
***** Call to <code>JRouter::_processParseRules</code> passing the URI
****** Call any custom routing rules (probably added via a system plugin using the <code>onAfterInitialise</code> event trigger) passing the URI
****** Returns an array of vars
***** If SEF mode, replace <code>start</code> variable with </code>limitstart</code>
**** If raw mode, call to <code>JRouterSite::_parseRawRoute</code> passing the URI
**** If SEF mode, call to <code>JRouterSite::_parseSefRoute</code> passing the URI
***** If the route (the URI path) is empty, load it from the default menu item; set the active menu item as the default
***** If first part is <code>/component/com_content</code>, set the <code>option</code> as the second segement. Null the <code>Itemid</code>.
***** Else, loop through menu alias values and take off segments that match as the menu tree is traversed. Set <code>option</code> and <code>Itemid</code> based on the last menu item found.
***** If the <code>Itemid</code> is set in the URL, set the active menu item based on this value.
***** Push the vars collected so far (eg, <code>option</code>, <code>Itemid</code>, etc) into the router object (<code>$this</code>).
***** If the route and <code>option</code> is set, load the component router;
***** Else, get the active menu item and get the route vars from it

== Application Route Building ==

TODO

== Custom Router Rules ==

TODO

== Additional References ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

J1.5:How to add breadcrumbs

2009-11-30T22:17:46Z

Creuzerm:

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/Joomla-Framework/Application/JPathway.html