[[TOC]]
= S3XRC - S3Request =

  - [wiki:S3XRC]

== S3Request and Method Handlers ==

When method handlers are called by the [wiki:S3XRC_S3Resource#RESTInterface REST interface], they get a S3Request object passed as the first argument, usually named "r" or "jr":

{{{
def method_handler(r, **attr):
}}}

This S3Request instance represents the request to be executed, and it contains references to all data necessary to perform the requested action.

  ''Note: All method handlers receive the same list of arguments, regardless of whether they are standard CRUD or custom method handlers.''
== Attributes of the S3Request ==

The following attributes are set during initialisation of an S3Request object, no further call is required.

=== Controller Attributes ===

||'''rc'''||the resource controller object (''S3ResourceController'')||
||'''request'''||the original web2py request (''Storage'')||
||'''session'''||the current session (''Storage'')||
||'''response'''||the web2py response (''Storage'')||

=== Request Attributes ===

||'''representation'''||the current representation of this request (''string'', lowercase)||
||'''http'''||the HTTP method of this request (''string'', always uppercase!)||
||'''extension'''||the extension found in the original request (''string'', lowercase)||
||'''method'''||the method of the request if not HTTP (''string'', always lowercase)||
||'''custom_action'''||the custom method handler for the request (''function'' or ''lambda'')||

=== Primary Resource Attributes ===

||'''prefix'''||the prefix (=module name) of the requested resource (''string'')||
||'''name'''||the name of the requested resource, without prefix (''string'')||
||'''tablename'''||the name of the primary table (''string'')||
||'''table'''||the primary table (''Table'')||
||'''id'''||the ID of the primary record (''int'')||
||'''record'''||the primary record (''Row'')||

=== Component Resource Attributes ===

||'''component'''||the requested component, if any (''!ObjectComponent'')||
||'''pkey'''||the primary key of the Resource/Component join (''string'')||
||'''fkey'''||the foreign key of the Resource/Component join (''string'')||
||'''component_name'''||the name of the component without prefix (''string'')||
||'''component_id'''||the ID of the component record as of the request, if any (''int'')||
||'''multiple'''||Flag indicating that multiple component records are allowed (''boolean'')||

=== Error Indicators ===

||'''error'''||the last error message (''string'')||
||'''invalid'''||Flag indicating this request as invalid (''boolean'')||
||'''badmethod'''||Flag indicating a bad method error (''boolean'')||
||'''badrecord'''||Flag indicating a invalid record ID error (''boolean'')||
||'''badrequest'''||Flag indicating an unqualified request error (''boolean'')||

'''!ObjectComponent''' contains:
  - '''prefix''', '''name''', '''tablename''', '''table''' and '''attr''' of the component
  - '''attr''' contains:
    - '''multiple''' Multiple-flag
    - '''editable''', '''deletable''' and '''listadd'''
    - '''list_fields''', '''rss''', '''main''' and '''extra'''
    - '''onaccept''', '''onvalidation''', '''delete_onaccept''' and '''delete_onvalidation'''
  - methods: '''set_attr()''' and '''get_attr()'''

== Methods of the S3Request ==

=== Magic URLs ===

'''here(representation=None)'''
  - returns the URL of the current request

'''there(representation=None)'''
  - returns the URL of a HTTP GET request for the same resource

'''same(representation=None)'''
  - returns the URL of the current request with the primary record ID replaced by the string literal '[id]'

'''other(method=None, record_id=None, representation=None)'''
  - returns the URL of a request with another method and record ID, but for the same resource

=== Other functions ===

'''target()'''
  - returns the target table of the current request as tuple of (prefix, name, table, tablename)