Supporting SEF URLs in your component - Revision history

Wilsonge: Update 3.0 to 3.1

2013-04-29T09:40:50Z

Update 3.0 to 3.1

Cmb: /* A Simple Example */ Corrected capitalization. Removed apostrophe.

2013-03-07T23:40:57Z

‎A Simple Example: Corrected capitalization. Removed apostrophe.

Wilsonge at 11:20, 19 February 2013

2013-02-19T11:20:15Z

Wilsonge at 11:20, 19 February 2013

2013-02-19T11:20:04Z

Mvangeest: Added information and removed Incomplete template - this page is not complete, but contains enough information to be useful

2012-11-25T18:17:47Z

Added information and removed Incomplete template - this page is not complete, but contains enough information to be useful

Mvangeest: Split off parts to Routing implementation details

2012-11-25T00:55:35Z

Split off parts to Routing implementation details

Mvangeest: Adjusted layout

2012-11-24T17:51:30Z

Adjusted layout

Mvangeest: Added information

2012-11-24T17:33:38Z

Added information

Mvangeest: Improved naming consistency

2012-08-22T14:28:32Z

Improved naming consistency

Mvangeest: Fixed mistake

2012-08-20T21:32:22Z

Fixed mistake

@@ Line 1: / Line 1: @@
-{{version|1.5,2.5,3.0}}
+{{version|1.5,2.5,3.1}}
 {{:Search Engine Friendly URLs}}
 In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

@@ Line 180: / Line 180: @@
 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 <tt>router.php</tt> is a very simple way to generate sef URL's but should show how this works quite clearly.
+The above example of the <tt>router.php</tt> is a very simple way to generate SEF URLs 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:

@@ Line 1: / Line 1: @@
 {{version|1.5,2.5,3.0}}
 {{:Search Engine Friendly URLs}}
 In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

← Older revision		Revision as of 11:20, 19 February 2013
Line 1:		Line 1:
		+	{{version\|1.5,2.5,3.0}}
		+
	{{:Search Engine Friendly URLs}}		{{:Search Engine Friendly URLs}}
	In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers\|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.		In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers\|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

@@ Line 1: / Line 1: @@
 {{:Search Engine Friendly URLs}}
 In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.
@@ Line 37: / Line 36: @@
 :<code>$segments = array(20, 1);</code>
-::<span style="font-size: xx-large">&darr;</span> Joomla's internal routing (for display)
+::<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>
@@ Line 45: / Line 44: @@
 :<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>
-::<span style="font-size: xx-large">&darr;</span> Joomla's internal routing
+::<span style="font-size: xx-large">&darr;</span> Joomla's internal route parsing
 :<code>$segments = array(20, 1);</code>
@@ Line 287: / Line 286: @@
 The result of all this code is clean and human-readable component URLs.
 == See Also ==

@@ Line 288: / Line 288: @@
 The result of all this code is clean and human-readable component URLs.
-== Application Route Parsing ==
+== See Also ==
-The [[Application 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 <tt>index.php</tt> file.
+There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)
-* Call to <code>JApplication::route</code>
+For details on the internals of routing, see [[Routing implementation details]].
-** 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)
 <noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

@@ Line 78: / Line 78: @@
 </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.
+If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the <code>JFilterOutput::stringURLSafe()</code> method.
 === The Slug ===
@@ Line 92: / Line 92: @@
 == Routing URLs ==
-The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <code>JRoute</code> has three parameters and its prototype is:
+The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <tt>JRoute</tt> has three parameters and its prototype is:
 <source lang="php">JRoute::_( $url, $xhtml = true, $ssl=null );</source>
@@ Line 115: / Line 115: @@
 * 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.
+* Create the component route. To create the component route, JRouter looks for the <tt>router.php</tt> 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).
+We will have two functions in the <tt>router.php</tt>. 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 (<code>view=categories</code>), the second is a single category (<code>view=category</code>) and the third is a single article (<code>view=article</code>).
-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.
+The file <tt>router.php</tt> 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 XML [[Manifest files|manifest file]] in the site folder.
 === A Simple Example ===
@@ Line 148: / Line 148: @@
 <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 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 <tt>/components/com_magic/...</tt> would use a prefix <code>magic</code> (all lower case).
-The next function in the <code>router.php</code> parses the URL:
+The next function in the <tt>router.php</tt> parses the URL:
 <source lang="php">
@@ Line 180: / Line 180: @@
 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 above example of the <tt>router.php</tt> 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>
+<tt><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></tt>
 === A More Advanced Example ===
@@ Line 192: / Line 192: @@
 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 an article: <tt><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></tt>
-* When viewing a category: <code><nowiki>http://www.example.com/[menualias]/[category]</nowiki></code>
+* When viewing a category: <tt><nowiki>http://www.example.com/[menualias]/[category]</nowiki></tt>
-* When viewing the categories overview: <code><nowiki>http://www.example.com/[menualias]</nowiki></code>
+* When viewing the categories overview: <tt><nowiki>http://www.example.com/[menualias]</nowiki></tt>
 Let's assume we have done step 1 and 2 also for the category.
@@ Line 210: / Line 210: @@
 </source>
-The corresponding <code>router.php</code>:
+The corresponding <tt>router.php</tt>:
 <source lang="php">
@@ Line 283: / Line 283: @@
 * 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 the categories view and the <code>$segments</code> array has one item (<code>$id</code>). 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 menu item is a link to a category. In this case, we know that any item in the <code>$segments</code> array is the identifier for an article.
 The result of all this code is clean and human-readable component URLs.
@@ Line 290: / Line 290: @@
 == Application Route Parsing ==
-The [[Application 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.
+The [[Application 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 <tt>index.php</tt> file.
 * Call to <code>JApplication::route</code>

@@ Line 5: / Line 5: @@
 == 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>. You'll 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>.
+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.
 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:

@@ Line 5: / Line 5: @@
 == 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>. You'll need to write a router, which is a single file (<code>/components/com_yourcomponent/router.php</code>) that transforms system URLs back and forth to human-readable URLs using two functions.
+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>. You'll need to write a router, which is a single file (<tt>/components/com_yourcomponent/router.php</tt>) with two functions that transform system URLs back and forth to human-readable URLs.
 The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the URL. Schematically, the transformation works as follows:
@@ Line 11: / Line 11: @@
 :<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</div>
+::<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>