Changes between Initial Version and Version 1 of S3/S3Method

01/28/11 01:11:35 (13 years ago)
Dominic König



  • S3/S3Method

    v1 v1  
     1= S3Method =
     3'''S3Method''' is an interface to implement method handlers for the [wiki:S3XRC/RESTfulAPI RESTful API]. Method handlers are used to perform requested actions on S3Resources, and produce the output for the view.
     5== Implementing Methods ==
     7Method handlers must be callable objects, i.e. they can be instances of classes which implement the __call__ method, lambdas or normal functions.
     9In any case, they must take the {{{S3Request}}} instance (representing the HTTP request) and a variable list of named arguments as parameters:
     13def my_method_handler(r, **attr):
     14    return dict()
     19my_method_handler = lambda r, **attr: dict()
     22Class and instance:
     24class MyMethodHandler:
     25    def __call__(r, **attr):
     26        return dict()
     28my_method_handler = MyMethodHandler()
     31The returned {{{dict}}} will be passed to the view, so it would usually contain the output data.
     33== S3Method Interface ==
     35The {{{S3Method}}} class implements the {{{__call__(r, **attr)}}} method, and adds some attributes and methods which are commonly needed in most method handlers:
     37  '''Attributes:'''
     38  - '''manager''': the S3ResourceController instance
     39  - '''session''': the session store
     40  - '''request''': the web2py Request instance
     41  - '''response''': the web2py Response instance
     42  - '''T''': the global translator object
     43  - '''db''': the global DAL instance (database)
     44  - '''download_url''': the default download-URL
     45  - '''method''': string containing the requested method
     47  '''Resource:'''
     48  - '''resource''': the S3Resource instance for the requested resource
     49  - '''prefix''': the application prefix ("Module" prefix)
     50  - '''name''': the name of the requested resource (without prefix)
     51  - '''table''': the corresponding database table
     52  - '''tablename''': the database table name
     53  - '''record''': the record ID specified in the URL
     55  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}}}.
     57  '''Methods:'''
     58  - '''permit''': check authorization (shortcut for auth.shn_has_permission)
     59  - '''_config''': gets a CRUD setting of the target table
     60  - '''_view''': finds the pathname of a custom view template
     62  '''Hooks:'''
     63  - '''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)
     65To implement a method handler as {{{S3Method}}}, you would typically subclass {{{S3Method}}} and implement the {{{apply_method}}} method:
     68class MyMethodHandler(S3Method):
     70    def apply_method(r, **attr):
     71        return dict()
     74For examples see modules/s3/ or modules/s3/