View source for Supporting SEF URLs in your component

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">&darr;</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">&darr;</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">&darr;</span> Joomla's internal route building (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">&darr;</span> Joomla's internal route parsing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">&darr;</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.