[[TOC]]
= S3Method =

'''S3Method''' is an interface to implement method handlers for the [wiki:S3#RESTfulAPI S3 RESTful API]. Method handlers are used to perform requested actions on S3Resources, and produce the output for the view.

== Implementing Methods ==

In general, method handlers must be callable objects, i.e. they can be instances of classes which implement the {{{__call__}}} method, lambdas or normal functions.

In any case, they must take the {{{S3Request}}} instance (representing the HTTP request) and a variable list of named arguments as parameters:

Function:
{{{#!python
def my_method_handler(r, **attr):
    return dict()
}}}

Lambda:
{{{#!python
my_method_handler = lambda r, **attr: dict()
}}}

Class and instance:
{{{#!python
class MyMethodHandler:
    def __call__(r, **attr):
        return dict()

my_method_handler = MyMethodHandler()
}}}

The returned {{{dict}}} will be passed to the view, so it would usually contain the output data.

== Configuring Methods ==

Methods of the RESTful API can be configured:

  a. using {{{s3db.set_method}}} for explicit URL methods
  b. using {{{S3Resource.set_handler}}} for a particular S3Resource instance

where ''a'' overrides ''b''.

The methods {{{create}}}, {{{read}}}, {{{update}}} and {{{delete}}} are pre-defined for all resources (=fallback to [wiki:S3XRC/S3CRUD S3CRUD]), however, they can be customized by {{{set_handler}}}.
== S3Method Interface ==

The {{{S3Method}}} class implements the {{{__call__(r, **attr)}}} method, and adds some attributes and methods which are commonly needed in most method handlers:

  '''Attributes:'''
  - self.'''manager''': the S3ResourceController instance
  - self.'''session''': the session store
  - self.'''request''': the web2py Request instance
  - self.'''response''': the web2py Response instance
  - self.'''T''': the global translator object
  - self.'''db''': the global DAL instance (database)
  - self.'''download_url''': the default download-URL
  - self.'''method''': string containing the requested method

  '''Resource:'''
  - self.'''resource''': the S3Resource instance for the requested resource
  - self.'''prefix''': the application prefix ("Module" prefix)
  - self.'''name''': the name of the requested resource (without prefix)
  - self.'''table''': the corresponding database table
  - self.'''tablename''': the database table name
  - self.'''record''': the record ID specified in the URL

  Note that, other than in {{{S3Request}}} instances, the resource attributes here refer to the target resource of the request, meaning, this would be the ''component'' if a component has been requested. To get at the parent resource, use {{{self.resource.parent}}}.

  '''Methods:'''
  - self.'''permit''': check authorization (shortcut for auth.shn_has_permission)
  - self.'''_config''': gets a CRUD setting of the target table
  - self.'''_view''': finds the pathname of a custom view template

  '''Hooks:'''
  - self.'''next''': URL to redirect to after the current request has been completed, typically set by the method handler (Note: this redirection does never happen after GET)

To implement a method handler as {{{S3Method}}}, you would typically subclass {{{S3Method}}} and implement the {{{apply_method}}} method:

{{{#!python
class MyMethodHandler(S3Method):

    def apply_method(r, **attr):
        return dict()
}}}

For examples see modules/s3/s3crud.py or modules/s3/s3search.py.