Components are reusable pieces of functionality that can be invoked via a controller or react to controller events. This are a great way to re-use code between controllers, such as with pagination, searching, emailing, etc.

Using Components

Import the components and include them in the Meta.components property on your controller, like so:

from ferris.components.pagination import Pagination
from import Search

class Documents(Controller):
    class Meta:
        components = (Pagination, Search)

Inside of your actions, you can access the component instances using self.components:

def list(self):

Creating Components

You can of course create your own components. Here’s a very simple component that listens for the startup event and logs:

class Logger(object):
    def __init__(self, controller):
        self.controller = controller += self.on_after_startup

    def on_after_startup(self, controller):"Hello!")

Built-in Components

The ferris.components module provides a few built-in components. These can be used directly, customized, or used as guidelines when building your own.


The Cache component provides utilities for doing client-side (edge) caching. This is not to be confused with memcache which is server-side caching.

class ferris.components.cache.Cache(controller)[source]

Provides easy methods to for setting edge caching, both via the browser and App Engine’s intermediate caching proxies.

Usage is pretty easy. Include the cache component and use the set_cache decorator.

ferris.components.cache.set_cache(mode='public', minutes=None)[source]

Decorator that calls the cache component automatically for an action

For example:

from ferris import Controller, route
from ferris.components.cache import Cache, set_cache

class Posts(Controller):
    class Meta:
        components = (Cache)

    @set_cache('public', 60*60)
    def list_all(self):

    @set_cache('private', 60*60)
    def list_mine(self):


The OAuth component is documented in OAuth2.


class ferris.components.pagination.Pagination(controller)[source]

Provides a generic, reusable Pagination API.

This can be used to automatically paginate ndb.Query objects but it can also be used directly to provide pagination over custom datasources.

Automatically happens for any list actions but can also be manually invoked via paginate() or __call__().

Pagination.paginate(query=None, cursor=None, limit=None)[source]

Paginates a ndb.Query and sets up the appropriate template variables.

Uses Controller.Meta.pagination_limit to determine how many items per page or defaults to 10 if omitted.

Returns the data, and if query is a string, sets that template variable.

If query is omitted it’ll attempt to find the dataset using the scaffold variable names.

For example of using this, see Extras

You can also use the pagination component to provide pagination for custom datasets such as external apis or CloudSQL. The pagination component can automatically keep track of previous cursors to provide backwards pagination. For example:

cursor, limit = self.components.pagination.get_pagination_params()

data, next_cursor = get_custom_data(cursor, limit)

Pagination.get_pagination_params(cursor=None, limit=None)[source]

Retuns the pagination parameters provided by the request. Use this in your custom APIs to determine which cursor and the number of objects the user is requesting.

Pagination.set_pagination_info(current_cursor=None, next_cursor=None, limit=None, count=None)[source]

Sets the pagintion information for the view context. Use by your custom APIs to expose the next cursor, the limit, and the number of objects currently visible.

Sets the paging template variable to a dictionary like:

    "cursor": "abc...",
    "previous_cursor": "rvx...",
    "next_cursor": "nzb...",
    "limit": 10,
    "count": 10

Returns the current pagination infomation from the view context: previous cursor, current cursor, next cursor, page, limit, and count.

There is also a helpful macro to print simple forward and backwards pagination controls:

{% import "macros/pagination.html" as p %}


Generates bootstrap style forward and backwards pagination arrows.


The search component is documented in the Uploads & Downloads section.