{{TOC}}
= Introduction =
Understanding the routing system is key to being able to develop for The Bug Genie. The Bug Genie uses an MVC-based framework, and the routing system is based on URL-rewriting. The routes are made up of fixed parts, and parameter parts, where parameter parts can vary, and will be passed on to the [[TheBugGenie:Development:Action|Actions]] via the [[TheBugGenie:Development:Requests|Request]].

The Bug Genie core adds routes via the ''load_routes.inc.php'' and ''load_routes_postmodules.inc.php'' files, parsed before and after modules are loaded. The reason this is being done in two stages is because project routes have to be added after all other routes. Modules can not add project routes, and will have to detect a project context by other means if that's desired.

= A route, explained =
A route is made up of three or more parts, specifically:
* The route key, which is used to refer to the route when you generate it
* The url, with any named parameters
* The module and action which will receive the request
* Optionally any additional request parameters you want to pass on to the action

Example from ''load_routes.inc.php'':
<source lang="php">
// The login route, accessible from http://host/subdir/login
// triggers the actions class in the "main" module and runs the
// "runLogin" action in that module
$routes[] = array('login', '/login', 'main', 'login');

// The reportissue route, accessible from http://host/subdir/reportissue with
// any following parameters (ex: /reportissue, /reportissue/something/1, etc)
// Same as above, this launches a function in the "main" module,
// namely the "runReportIssue" function
$routes[] = array('reportissue', '/reportissue/*', 'main', 'reportIssue');
</source>

Example from the '''publish''' module:
<source lang="php">
protected function _addAvailableRoutes()
{
	// Since this is a module route, it will be passed to the module
	// action class automatically, so this doesn't need to be specified
	// 
	// This route will be forwarded to the "runShowArticle" action in the publish actions class
	// and, the request parameter "article_name" will be available in that action
	$this->addRoute('publish_article', '/wiki/:article_name', 'showArticle');
}
</source>

== The route key and parameters ==
The route key is what you use when you refer to this route to generate the url. This can be generated one of two ways, depending on where in the system you are. In the [[TheBugGenie:Development:Templates|view]] ([[TheBugGenie:Development:Templates|templates]]), you use the '''make_url()''' function, which takes one or two parameters, depending on how you refer to the route key.
<source lang="php">
// This takes the route name and an associative array of parameters.
make_url($route_name, $parameters, $relative = true);

// This takes a string with a named route, starting with an "@"-sign, 
// followed by parameters provided as "?parameter_1=value_1&parameter_2=2"
// just as a regular URL
make_url($route_name_with_parameters, $parameters, $relative = true);
</source>

Examples:
<source lang="php">
echo make_url('configure_module', array('module_name' => 'publish'));
// outputs "/configure/module/publish"

echo make_url('configure_module', array('module_name' => 'publish'), false);
// outputs "http://hostname/subdirectory/configure/module/publish"

echo make_url('reportissue', array('parameter_1' => 'value_1', 'parameter_2' => 'value_2'));
// outputs "/reportissue/parameter_1/value_1/parameter_2/value_2"

$module = 'publish';
echo make_url("@configure_module?module_name={$module_name}");
// outputs "/configure/module/publish"

echo make_url("@configure_module?module_name=mailing", array(), false);
// outputs "http://hostname/subdirectory/configure/module/mailing"
</source>

Alternatively if you you're in an action / component and you need to generate a URL, you can use the '''generate()''' function in the '''TBGRouting''' class directly. The '''make_url()''' function is a shortcut to this function ('''TBGRouting::generate()'''), so the behavior of the two function is identical. ''Remember that you need that instantiated routing object, which means you have to access it through the '''TBGContext''' class' '''getRouting()''' function.''

Here is the example from above, with the '''generate()''' function instead:
<source lang="php">
echo TBGContext::getRouting()->generate('configure_module', array('module_name' => 'publish'));
// outputs "/configure/module/publish"

echo TBGContext::getRouting()->generate('configure_module', array('module_name' => 'publish'), false);
// outputs "http://hostname/subdirectory/configure/module/publish"

echo TBGContext::getRouting()->generate('reportissue', array('parameter_1' => 'value_1', 'parameter_2' => 'value_2'));
// outputs "/reportissue/parameter_1/value_1/parameter_2/value_2"

$module = 'publish';
echo TBGContext::getRouting()->generate("@configure_module?module_name={$module_name}");
// outputs "/configure/module/publish"

echo TBGContext::getRouting()->generate("@configure_module?module_name=mailing", array(), false);
// outputs "http://hostname/subdirectory/configure/module/mailing"
</source>

The '''make_url()''' function is only loaded after the ''ui'' library has been loaded. This happens when the template has been parsed (or any template has been parsed), so the '''make_url()''' function is only safe to call inside templates. Anywhere else you should use the '''TBGRouting::generate()''' function.

= Incoming requests =
When an incoming request is received - after the framework has been loaded - The Bug Genie will look through all its registered routes for a route that matches the URL, from the first route registered until the last route added has been checked. If two routes matches the same URL pattern, the first route will be used. If a match is found in the registered routes, The Bug Genie will look at the selected route and load the specified module action class, and execute the specified module action.

From the example above:
<source lang="php">
$this->addRoute('publish_article', '/wiki/:article_name', 'showArticle');
</source>
If a request is received and the URL matches the url pattern (f.ex.: "/wiki/Myarticle"), The Bug Genie will load up an instance of the publish module's action class (since this route was added from the publish module) and execute the public '''runShowArticle()''' method on that action object. Any additional parameters specified in the route will be passed to the action as request parameters in the request object. (See more about actions in the [[TheBugGenie:Development:Actions|action documentation]])

When the action method has finished successfully one of two things can happen. Depending on the return value of the action method, either the action's template file will be presented - with or without surrounding decoration (this also dependant on what happened in the action), or action output is presented / returned. For instance, The Bug Genie will not decorate ajax responses with header, menus and footer, but will only return the output from the action or its associated template. (See more about actions in the [[TheBugGenie:Development:Template|template documentation]])


[[Category:TheBugGenie:Development]]