OVERVIEW

CONCEPTS

Dispatcher

The foundation of every web framework is a tiny black box connecting incoming requests with code generating the appropriate response.

GET /user/show/1 -> $self->render(text => 'Sebastian');

This black box is usually called a dispatcher. There are many implementations using different strategies to establish these connections, but pretty much all are based around mapping the requests path to some kind of response generator.

While it is very well possible to make all these connections static, it is also rather inefficient. That's why regular expressions are commonly used to make the dispatch process more dynamic.

qr|/user/show/(\d+)| -> $self->render(text => $users{$1});

Modern dispatchers have pretty much everything HTTP has to offer at their disposal and can use many more variables than just the request path, such as request method and headers like Host, User-Agent and Accept.

Routes

While regular expressions are quite powerful they also tend to be unpleasant to look at and are generally overkill for ordinary path matching.

qr|/user/show/(\d+)| -> $self->render(text => $users{$1});

This is where routes come into play, they have been designed from the ground up to represent paths with placeholders.

/user/show/:id -> $self->render(text => $users{$id});

The only difference between a static path and the route above is the :id placeholder. One or more placeholders can be anywhere in the route.

/user/:action/:id

A fundamental concept of the Mojolicious router is that extracted placeholder values are turned into a hash.

/user/show/23 -> /user/:action/:id -> {action => 'show', id => 23}

This hash is basically the center of every Mojolicious application, you will learn more about this later on. Internally routes get compiled to regular expressions, so you can get the best of both worlds with a little bit of experience.

/user/show/:id -> qr/(?-xism:^\/user\/show/([^\/\.]+))/

A trailing slash is always optional.

/user/show/23/ -> /user/:action/:id -> {action => 'show', id => 23}

Reversibility

One more huge advantage routes have over regular expressions is that they are easily reversible, extracted placeholders can be turned back into a path at any time.

There are a few stash values with special meaning, such as controller and action, but you can generally fill it with whatever data you need to generate a response. Once dispatched the whole stash content can be changed at any time.

Special stash values (controller and action)

When the dispatcher sees controller and action values in the stash it will always try to turn them into a class and method to dispatch to. The controller value gets camelized and prefixed with a namespace (defaulting to the applications class) while the action value is not changed at all, because of this both values are case sensitive.

Controller classes are perfect for organizing code in larger projects. There are more dispatch strategies, but because controllers are the most commonly used ones they also got a special shortcut in the form of controller#action.

You can also adjust the regular expressions behind placeholders to better suit your needs. Just make sure not to use ^ and $ or capturing groups (...), because placeholders become part of a larger regular expression internally, (?:...) is fine though.

This for example allows multiple templates for different formats to share the same code. You can also mention a format in the route pattern to only match one, just make sure the more specific routes go first.

Embedding applications

You can easily embed whole applications simply by using them instead of a controller. This allows for example the use of the Mojolicious::Lite domain specific language in normal Mojolicious controllers.