Routing

Ferris will automatically create a route name and url for every action in every handler in your application. You can also specify additional routes using the file app/routes.py.

Parts

Actions in your application are referenced using four parts:

• The name of the handler
• 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 url for a particular action.

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:

Action	URL	name
Time.stop()	/time/stop	time-stop
Daleks.exterminate(who)	/daleks/exterminate/<who>	daleks-exterminate
Numbers.range(min, max)	/numbers/range/<min>/<max>	numbers-range
Spaceships.xml_specs()	/xml/spaceships/specs	xml-spaceships-specs
UserComments.json_stats	/json/user_comments/stats	json-user_comments-stats

CRUD Actions

The methods named list, view, add, edit, and delete are always treated as actions and are implicitly routed (even when prefixed).

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

Action	URL
list	/handler
add	/handler/add
view	/handler/<id>
edit	/handler/<id>/edit
delete	/handler/<id>/delete

Non-CRUD Actions

Other methods 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 code.

ferris.core.handler.route(f)

Marks a class method to enable it to be automatically routed and accessible via HTTP. This decorator should always be the outermost decorator.

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

ferris.core.handler.route_with(*args, **kwargs)

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

Parameters:template – Sets the URL template for this action

For example:

@route_with(template='/ultimate/life/form')
def daleks(self):
    return 'Daleks'

Prefixes

Prefixes must be explicitly listed in the prefix class property in a handler, for example:

class Posts(Handler):
    prefixes = ['json']

    @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.

Generating URLs to Actions

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

Handler.uri(route_name = None, prefix = <sentinel>, handler = <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, handler, 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.
• handler – The handler name of the desired URI, if omitted then the current handler 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, handler='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:

Handler.uri_exists(route_name=None, prefix=<object object at 0x31291a0>, handler=<object object at 0x31291a0>, action=<object object at 0x31291a0>, *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:

Handler.on_uri(route_name=None, prefix=<object object at 0x31291a0>, handler=<object object at 0x31291a0>, action=<object object at 0x31291a0>, **kwargs)

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

Static Files

Static files live in app/static and can be accessed via http://localhost:8080/static.

The folders css, js, and img are aliased and can be accessed via http://localhost:8080/css, http://localhost:8080/js, and http://localhost:8080/img respectively.

Plugin assets are available via http://localhost:8080/plugins/plugin_name/.