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 Actions via the 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:

// 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');

Example from the publish module:

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');
}

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 view (templates), you use the make_url() function, which takes one or two parameters, depending on how you refer to the route key.

// 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);

Examples:

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"

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:

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"

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:

$this->addRoute('publish_article', '/wiki/:article_name', 'showArticle');

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 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 template documentation)