Warning! This page has the following tags:

• This page needs to be merged with docbook documentation.

Managing Routes

Tradional web applications use and produce urls like www.example.com/page.foo?nastylooking=parameters&p2=value2&printable=yes. Routes (the term 'routing' was made famous by Ruby on Rails, routes are sometimes also called Search Engine Friendly urls) are a new way of doing this. Consider the url shown earlier. Now, would you prefer this: www.example.com/parameter/value2/print. I know I would.

Agavi makes it possible to use routes and define even quite complex rules to process them. Luckily Agavi takes care of all things complex and your part is a breeze. By default Agavi routes have index.php (ie. www.example.com/index.php/fancy/route/) in front of them but you can get rid of it by using mod_rewrite and a simple .htaccess file.

Requirements

• if you want to get rid of the index.php in the URL, you need mod_rewrite module for Apache and proper rights to modify httpd.conf or .htaccess files (AllowOverride and so on, check Apache manual for more information).
• <setting name="use_routing">true</setting> in settings.xml

Basics

• Routes are processed in the order they are specified. Remember this if you define complex routes.
• Route definition can have children.
• Route patterns can include parameters that are passed to Request and re-parsed back when you generate a route url.

Simple Routes

<configurations>
	<configuration>
		<routes>
			<route name="page1" pattern="/page1" module="Pages" action="ShowPage1" />
			<route name="index" pattern="^/$" module="%actions.default_module%" action="%actions.default_action%" />
		</routes>
	</configuration>
</configurations>

The first route here is pretty obvious: www.example.com/page1 triggers action Pages.ShowPage?1. The second route is also simple. Regular expression ^/$ means "begin of line followed by a slash and end of line". So www.foo.invalid/ triggers what ever you have defined as your default action. Note the %actions.default_...% syntax.

If no route matches Agavi will automatically trigger 404 action defined in settings.xml.

Parameter defaults are explained below.

Content Type

<route name="print" pattern="/print$" output_type="html_print" />
<route name="pdf" pattern="/pdf$" output_type="pdf" />

Now this is one thing that makes Agavi routes awesome. As you hopefully know Agavi handles multiple output types (html, xml, printable html, pdf and so on) for the same action easily and almost transparently. With the output_type attribute in route definitions you can make this even more transparent and easy.

Routes and patterns are - once again - dead simple: www.foo.invalid/page1/print will serve the content as html_print and www.foo.invalid/page1/pdf as pdf. Output types, renderers, fallbacks and defaults are defined in output_types.xml.

Parameters in Routes

Simple example

<route name="viewproduct" pattern="/products/(prdid:\S+)" module="Products" action="View" />

usage: http://www.example.com/products/123

Now you can access prdid through Request::getParameter (in most cases like this: $this->getContext()->getRequest()getParameter('prdid')).

To generate a route to show product 321, you'd use $this->getContext()->getRouting()->gen('viewproduct', array('prdid' => '321'));

Default Values

<route name="viewproduct" pattern="/products/(prdid:\S+)" module="Products" action="View">
	<defaults>
		<default for="prdid">1000</default>
	</defaults>
</route>

Now route generation method will use '1000' as a default value if you don't explicitly give prdid as a parameter.

More Complex Use of Parameters

<route name="prdsearch" pattern="/search" module="ProductSearch" action="ShowSearchForm">
	<routes>
		<route name="prdautosearch" pattern="/(prdline:\S)/(prdid:\S+)" action="Search" />
		<route name="prdautosearch2" pattern="/(prdid:\S+)" action="Search" />
	</routes>
	<defaults>
		<default for="prdline">A</default>
	</defaults>
</route>

• www.example.com/search shows the search form.
• www.example.com/search/B/prd123 searches for a 'prd123' from the product line 'B'.
• www.example.com/search/prd123 searches for a 'prd123' from the default product line 'A'.

Note that definitions are inherited from parents so children don't have to re-declare module for example.