Routes and Controllers

A route is the logic that matches the URL requested by a visitor with the page where they want to go. The Route class handles the routing process, delegating authority to a designated controller. In a standard Chyrp Lite installation, there are two controllers: Main and Admin. The main controller can determine all the actions a visitor to your blog might want to take, such as viewing pages and doing searches, whilst the admin controller determines the actions a logged-in administrator might want to take. Below is a list of actions handled by the Main controller.

Action	Description
index	The blog index (also default action)
view	Viewing an individual blog post
login	Log-in page for registered users
logout	Log-out the current user
register	User registration page
lost_password	Password recovery page
search	Results page for searches
archive	The blog archive pages
feed	Redirects to the RSS feed

How do routes work?

The ultimate aim of routing is to determine an action: the action corresponds to a PHP function that will be called and expected to serve the page the visitor wants to see. Firstly the Route class will decompose the requested URL and make an initial attempt to determine the action. Next the Route class will hand over to the controller. It's the job of the controller to parse the URL and build a list of actions that "look like" the URL should go to them. The controller then hands back to the Route class to try each action in turn. Here is the workflow Chyrp Lite uses when you request a URL:

1. Receive URL request.

• Controller is prepared.
• Route is initiated with the prepared controller.
• Route makes an initial attempt at determining the action.
• Route gives the controller the opportunity to determine the action.
• Route loops through all potential actions until one returns true.

Once a potential action returns a value that evaluates to true the Route class will stop trying alternatives. The responding function uses the controller to display the page for the visitor. If Route tries all the possibilities and all return false it will direct the visitor to a fallback page or the 404 (not found) error page as a last resort.

Custom Routes

Custom routes tell Chyrp Lite to interpret a specific URL (relative to your install) as a particular combination of action and parameters. Custom routes are defined in the file config.json.php which can be found in the includes folder of your Chyrp Lite installation.

Adding Custom Routes Manually

To define a custom route manually, open the file config.json.php in a text editor and add your routes to the "routes" object in the file. For example, the following would tell Chyrp Lite to interpret http://yourdomain.com/blog as the blog's index action:

"routes": {
    "blog": "index"
},

Another example – interpret http://yourdomain.com/stuff as the tag action and tell the Tags module to show posts tagged with “foo”:

"routes": {
    "stuff": "tag;name=foo"
},

Multiple comma-separated routes can be added to the object:

"routes": {
    "blog": "index",
    "stuff": "tag;name=foo"
},

Adding Custom Routes Programatically

Modules can add a custom route by calling the add() method of the Route class. When a route is added programatically, it will be saved to config.json.php therefore routes should be added one time only in your module's __install() function and removed in the __uninstall() function. See the Tags module for an example:

Route::current()->add("tag/(name)/", "tag");

As part of the routing process, the route will search for trigger functions with names that match the current controller and action. The Tags module implements a main_tag() trigger function to enable it to respond when the Main controller is initiated with the tag action.

If your module adds custom routes it should also implement the parse_urls($urls) function. This function provides the controller with a regular expression it can use to parse your custom route, to determine if the URL is intended for you and also to translate a prettified "clean" URL into a "dirty" argument set. See the Tags module for an example:

public function parse_urls($urls) {
    $urls["|/tag/([^/]+)/|"] = "/?action=tag&name=$1";
    return $urls;
}

Responding to Actions Without a Custom Route

Your module can also respond to an action using a trigger function even if it has not added a custom route. As part of the routing process, the route will search for matching trigger functions of the pattern route_<<action>>() and your module will be able to respond if it has a function named after the corresponding action. For example, the Likes module uses a route_like() trigger function to respond when a visitor clicks on a "Like!" link with the URL /?action=like. This method should be used only for actions that do not display content, because it does not allow for clean to dirty URL translation.

Targeting Actions

When you browse your blog, route actions will appear in your web browser's address bar as part of the URL path. Your blog themes and modules can inspect the action and respond differently to different actions.

Actions in Twig

The following statement will evaluate to true only if the current page is the blog index:

{% if route.action == "index" %}

You can use Twig to insert the correct URL for a particular action into your blog pages:

{{ url('archive') }}

Actions in PHP

The following statement will evaluate to true only if the current page is the blog index:

if (Route::current()->action == "index")

You can also request the correct URL for an action by supplying the action to the url() helper function:

url("archive");