Routing
Overview
All components in Joomla! can be accessed through a query string by using the option
parameter which will equate to the name of the
component. For example, to access the "Contacts" component, you could type http://yourhub.org/index.php?option=com_contact
.
When SEF URLs are being employed, the first portion after the site name will almost always be
the name of a component. For the URL http://yourhub.org/contact
, the first portion after the slash translates to the
component com_contact
. If a matching component cannot be found, routing will attempt to match against an article section, category, and/or page alias.
While not required, most components will have more detailed routing instructions that allow SEF URLs to be
made from and converted back into query strings that pass necessary data to the component. This is done by the inclusion of a file called router.php
.
router.php
Every router.php
file has two methods: {ComponentName}BuildRoute()
which takes a query string and turns it into a SEF URL and {ComponentName}ParseRoute()
which deconstructs a SEF URL back into a query string to be passed to the component.
function ExampleBuildRoute(&$query) { $segments = array(); if (!empty($query['task'])) { $segments[] = $query['task']; unset($query['task']); } if (!empty($query['id'])) { $segments[] = $query['id']; unset($query['id']); } if (!empty($query['format'])) { $segments[] = $query['format']; unset($query['format']); } return $segments; } function ExampleParseRoute($segments) { $vars = array(); if (empty($segments)) { return $vars; } if (isset($segments[0])) { $vars['task'] = $segments[0]; } if (isset($segments[1])) { $vars['id'] = $segments[1]; } if (isset($segments[2])) { $vars['format'] = $segments[2]; } return $vars; }
{ComponentName}BuildRoute()
This method is called when using JRoute::_()
. JRoute::_()
passes the query string (minus the option={componentname}
portion) to the method which
returns an array containing the necessary portions of the URL to be constructed in the order
they need to appear in the final SEF URL.
// $query = 'task=view&id=123&format=rss' function ExampleBuildRoute(&$query) { $segments = array(); if (!empty($query['task'])) { $segments[] = $query['task']; unset($query['task']); } if (!empty($query['id'])) { $segments[] = $query['id']; unset($query['id']); } if (!empty($query['format'])) { $segments[] = $query['format']; unset($query['format']); } return $segments; }
Will return:
Array( 'view', '123', 'rss' );
This will in turn be passed back to JRoute::_()
which will construct the final SEF URL of example/view/123/rss
.
{ComponentName}ParseRoute()
This method is automatically called on each page view. It is passed an array of segments of the SEF URL that called the page. That is,
a URL of example/view/123/rss
would be separated by the forward slashes with the first segment automatically
being associated with a component name. The rest are stored in an array and passed to {ComponentName}ParseRoute()
which then associates each segment with an appropriate
variable name based on the segment's position in the array.
function ExampleParseRoute($segments) { $vars = array(); if (empty($segments)) { return $vars; } if (isset($segments[0])) { $vars['task'] = $segments[0]; } if (isset($segments[1])) { $vars['id'] = $segments[1]; } if (isset($segments[2])) { $vars['format'] = $segments[2]; } return $vars; }
Note: Position of segments is very important here. A URL of example/view/123/rss
could yield completely different results than a URL of example/rss/view/123
.