Routes

(originally from http://chyrp.net/community/comments.php?DiscussionID=871)

Routes are what determine what you want to do or where you want to go with the given URL. It’s their job to parse the URL, and figure out what to do from there, by trying things that “look like” the URL should go there. For example, viewing a post by http://example.com/my-post, which looks like viewing a basic action like http://example.com/drafts. It will attempt to run the “view post” action first, and if that fails it’ll just keep going until 1) one works or 2) it throws a 404.

Custom routes are just ways of mapping a certain URL (relative to your install) to a particular action, so when they view that URL it is interpreted as whatever you set it to.

For example:

routes:
  blog: index
  stuff: tag;name=stuff

This would map “http://example.com/blog” to “http://example.com/index”, which is another way of saying just “http://example.com/”. It would also map “http://example.com/stuff” to the “view tag” page, with “stuff” being the tag being viewed.

It basically goes like this:

Browser requests URL
          |
          v
Controller is prepared
          |
          v
Route is initiated with the prepared controller
          |
          v
Route determines based on the requested URL which actions to attempt
          |
          v
Route loops through all possible solutions until one doesn't return "false."
          |
          v
Fin.

The basic goal is to get the best possible page to be displayed for any given request. For example, what if you have the post URL set to something simple like “(url)”, and you also had a tag viewing page configured like this?:

routes:
  (name): tag

This would seemingly conflict with the “(url)”, since “http://example.com/this-is-a-tag” and “http://example.com/this-is-a-post” are essentially one and the same, in terms of appearance – it’s ambiguous.

So what Route does is toss them both in the “try” queue. It loops through that queue and calls the appropriate methods or controller actions. It will stop at the first action that doesn’t return “false” (indicating failure or a suboptimal route, e.g. a post or tag wasn’t found). (The method/controller action is responsible for displaying the page, so all Route has to do is stop.)

Additional comments from Alex:

alexsuraci: the main_xxxx (for the main controller), admin_xxxx (for the admin controller, in /admin), and route_xxxx (general, responds to everything) actions are called before the "official" controller methods
alexsuraci: the main_xxxx and admin_xxxx are named after their controllers dynamically (MainController and AdminController)
alexsuraci: it's best to think of Chyrp as a framework
alexsuraci: anyway, if you want to override an "official" controller method, your function should just return "true" and it won't try them
alexsuraci: but you don't have to since it's your own route anyway
alexsuraci: but you'd want to do that if you wanted to override "/drafts" with main_drafts, for example
alexsuraci: if any of this makes sense :P

Clarifications from Jon:

• If you want to define custom routes, that should happen in includes/config.yaml.php.
• If you do NOT configure custom routes, default processing will still happen. Modifying routes in config.yaml.php is only for advanced stuff.