Version 33 (modified by Dominic König, 14 years ago) ( diff )


S3XRC | S3 RESTful API | s3_rest_controller



The so-called REST Controller (function s3_rest_controller()) is a helper function to easily apply the RESTful API of the S3Resource class to your controller.

s3_rest_controller does:

  • parse and execute the incoming HTTP request on the specified resource
  • populate and hand-over view variables
  • choose and set the response view template (response.view)

Using s3_rest_controller, a basic RESTful controller for the pr_image table can look like:

def image():

    """ RESTful CRUD controller """

    return s3_rest_controller("pr", "image")

This exposes all standard URLs and methods for this table, including:

  • interactive create, read, update, delete and list views
  • non-interactive data export/import (GET/POST/PUT/DELETE) in multiple formats

Basic Syntax

output = s3_rest_controller(prefix, resourcename)
  • prefix is the application prefix of the resource
  • resourcename is the name of the resource (without prefix)
  • output contains the result of the request and can be returned from the controller as-is
    • in interactive view formats, this is a dict of view variables

Basic Options


Default destination of the redirection after a create or update is the read view of the processed record, after a delete it is the list view of the respective table.

The redirection destination can be configured per DB table, using:

s3xrc.model.configure(table, create_next=url)
s3xrc.model.configure(table, update_next=url)
s3xrc.model.configure(table, delete_next=url)


  • table is the respective DB table
  • url is the URL to redirect to

If, for create_next or update_next, url contains the string literal "[id]" (or its URL-encoded equivalent), then this literal is replaced by the ID of the updated/newly created record before redirection.


For every DB table, you can define functions to be invoked upon certain CRUD events. Those "callbacks" can be:

  • a single callable (function, lambda, callable object)
  • a list of callables, which are invoked in list order
  • a dict of callables, where the tablename is used as key to find the callable to be invoked
  • a dict of lists of callables, where the tablename is used as key to find the list of callables to be executed in list order

The return value of the callables, if any, is ignored.

Validation Callbacks

After successful submission of a create/update form (=the input data have successfully passed the field validation), you can define extra form validation methods to be invoked by using:

s3xrc.model.configure(table, create_onvalidation=callback)
s3xrc.model.configure(table, update_onvalidation=callback)


  • table is the respective DB table
  • callable is the callback setting, see Callbacks

If either of create_onvalidation or update_onvalidation is not set, then the onvalidation setting is tried:

s3xrc.model.configure(table, onvalidation=callback)

This allows you to define a common onvalidation callback for both create and update.

Onvalidation callbacks are meant to allow additional form data validation (beyond individual field validators). The callables receive the form as first and only parameter, while their return values will be ignored.

Any validation errors are to be reported directly into the form as:

form.errors[fieldname] = error_msg


  • fieldname is the field containing the invalid value
  • error_msg is the error message to be displayed in the form close to that field

If after the execution of the onvalidation callback any messages are found in form.errors, then no data are being imported and instead, the process will return to the input view with the messages displayed close to the respective form fields.

Important: In non-interactive data imports, the error message will be added to the import tree as extra attribute of the invalid element. The XML importer will however process all records in the import tree in order to find all validation errors before reporting the invalid tree to the sender, and in case ignore_errors is used, all valid records will be imported in the first attempt. Therefore the callback must not redirect!

On-accept Callbacks

On-Delete Callback


The default pagination method is server-side (SSPag), meaning, in list views the client will receive only the first of the available rows, and then retrieve more rows as needed by subsequent Ajax calls.

In contrast to that, in client-side pagination (CSPag) mode all available rows of the list are retrieved and send to the client at once. For most tables, though, this will probably be a huge data set and take a long time to extract and transmit, while mostly being unnecessary when the user only needs to see the first 20 rows to find what he's looking for.

However, some tables may by their nature only contain one or few rows, and then server-side pagination is not needed (in fact, inefficient). In these cases, the respective controller can turn it off by:


View Control

Default View

Custom View

Additional View Variables

In interactive view formats, any additional named arguments in the s3_rest_controller argument list will be added to the view variables:

output = s3_rest_controller(prefix, resourcename, **attr)
  • attr: additional view variables
  • any callable argument will be invoked with the S3Request as first and only argument, and its return value will be added to the view variables
  • any non-callable argument will be added to the view variables as-is
  • any argument that gives None will remove this key from the view variables

A typical use-case is rheader:

def my_rheader(r):
  if r.interactive and r.component:
    # Code producing the rheader...
    return rheader
    return None

output = s3_rest_controller(prefix, name, rheader=my_rheader)

If my_rheader(r) gives something else than None, then this value is added as rheader to the view variables.

Advanced Options



Method Handlers

Custom Methods


Note: See TracWiki for help on using the wiki.