Routing¶

Parts¶

A route is automatically generated using four parts determined from the route function:

• The name of the controller
• The prefix, if specified
• The name of the action
• The parameters of the action, if any

These are called the route parts and are used to build both the route name and the route url from the route function.

URL and Name Generation¶

For the route name, it follows the convention [prefix:]handler:action with handler being underscored.

For the url, it follows the convention [/prefix]/handler/action[/param_1, etc.] with handler being underscored.

The following table demonstrates various mappings:

CRUD Actions¶

The methods named list, view, add, edit, and delete are always treated as actions and are implicitly routed (even when prefixed). This means you don’t have to use the @route decorator to expose these actions and there’s no way to unexpose these.

These methods have preset url mappings as follows, but can be prefixed:

Non-CRUD Actions¶

Actions other than the CRUD actions need to be explicitly routed using @route or @route_with.

Take the following methods for example:

def list(self):
    return 'list'

@route
def test(self):
    return 'test'

def run(self):
    return 'run'

The methods list and test will be accessible via HTTP, but the method run is only accessible from within your code.

ferris.core.controller.route(f)[source]¶

Marks a method for automatically routing and accessible via HTTP. See routing for more details on how methods are auto-routed. This decorator should always be the outermost decorator.

For example:

@route
def exterminate(self):
    return 'EXTERMINAAATE!'

To set a custom url or name for an action, use @route_with

ferris.core.controller.route_with(*args, **kwargs)[source]¶

Marks a class method to be routed similar to route() and passes and additional arguments to the webapp2.Route constructor.

Parameters:	template – Sets the URL template for this action

For example:

@route_with(template='/posts/archive/<year>')
def archive_by_year(self, year):
    pass

Prefixes¶

A prefix is just a simple string that is placed before the action name, route name and url. It’s useful for grouping actions. You might use the ‘admin’ prefix to group together actions for an administrator and the ‘api’ prefix to group together actions that return machine-readable data instead of html.

Prefixes must be explicitly listed in the prefixes property in the Meta configuration for a Controller. For example:

class Posts(Controller):
    class Meta:
        prefixes = ('json', 'admin')

    @route
    def json_stats(self):
        pass

    @route
    def xml_stats(self):
        pass

json_stats will have the url /json/posts/stats but xml_stats will be at /posts/xml_stats because there isn’t a prefix setup for ‘xml’.

Generating URLs to Actions¶

There is a standard way to generate URLs to actions across the application:

Controller.uri(route_name = None, prefix = <sentinel>, controller = <sentinel>, action = <sentinel>, _pass_all = False, _full = False, *args, **kwargs)¶

Generate in-application URIs (or URLs).

Parameters:

route_name – The route name for which to generate a URI for, if not provided then prefix, controller, and action will be used to determine the route name prefix – The prefix of the desired URI, if omitted then the current prefix is used. controller – The controller name of the desired URI, if omitted then the current controller is used. action – The action name of the desired URI, if omitted then the current action is used. _pass_all – will pass all current URI parameters to the generated URI (useful for pagination, etc.) _full – generate a full URI, including the hostname. kwargs – arguments passed at URL or GET parameters.

Examples:

uri('foxes:run') # -> /foxes/run
uri(prefix=False, controller='foxes', action='run')  # -> /foxes/run

# when currently at /foxes/run
uri(action='hide') # -> /foxes/hide

Attempting to generate a URL to an action that doesn’t exist will result in an exception.

Checking if an action exists¶

You can check for the existence of an action before attempting to generate a URL to it:

Controller.uri_exists(route_name = None, prefix = <sentinel>, controller = <sentinel>, action = <sentinel>, *args, **kwargs)¶

Check if a route exists.

You can see if you’re on a particular action. While this may seem like a superfluous feature, it’s very useful in templates:

Controller.on_uri(route_name = None, prefix = <sentinel>, controller = <sentinel>, action = <sentinel>, *args, **kwargs)¶

Checks to see if we’re currently on the specified route.

Manual Routing¶

Your application’s route configuration is located in app/routes.py. You can configure custom routes such as the application root and additional redirects. Plugins can also be enabled using this configuration file.

# Default root route
routing.default_root()

# Default root route
routing.redirect('/', to='/posts')

routing.add(routing.Route('/special', SpecialHandler))

# Routes all App handlers
routing.auto_route()

from app.controllers.posts import Posts
routing.route_controller(Posts)