[[TOC]]
[wiki:S3XRC] | [wiki:S3XRC/RESTfulAPI S3 RESTful API] | s3_rest_controller
= s3_rest_controller =

== Introduction ==

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 [wiki:S3XRC/RESTfulAPI/URLFormat URLs] and [wiki:S3XRC/RESTfulAPI 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 ==

=== Redirection ===

=== Callbacks ===

=== Pagination ===

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 rows of a list are retrieved and send to the client at once, while the client arranges them in pages. This can though be a huge data set which takes a long time to extract it, which can be unefficient 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 have one or few rows, and then server-side pagination is not needed. In these cases, the respective controller can turn it off by:

{{{
response.s3.no_sspag=True
}}}
== 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
  else:
    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 ==

=== Pre-Process ===

=== Post-Process ===

=== Method Handlers ===

=== Custom Methods ===

----

DeveloperGuidelines