Changes between Initial Version and Version 1 of S3/S3Method

Timestamp:

01/28/11 01:11:35 (14 years ago)

Author:

Dominic König

Comment:

--

S3/S3Method

@@ +1 @@
+= S3Method =
+
+'''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.
+
+== Implementing Methods ==
+
+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:
+{{{
+def my_method_handler(r, **attr):
+    return dict()
+}}}
+
+Lambda:
+{{{
+my_method_handler = lambda r, **attr: dict()
+}}}
+
+Class and instance:
+{{{
+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.
+
+== 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:'''
+  - '''manager''': the S3ResourceController instance
+  - '''session''': the session store
+  - '''request''': the web2py Request instance
+  - '''response''': the web2py Response instance
+  - '''T''': the global translator object
+  - '''db''': the global DAL instance (database)
+  - '''download_url''': the default download-URL
+  - '''method''': string containing the requested method
+
+  '''Resource:'''
+  - '''resource''': the S3Resource instance for the requested resource
+  - '''prefix''': the application prefix ("Module" prefix)
+  - '''name''': the name of the requested resource (without prefix)
+  - '''table''': the corresponding database table
+  - '''tablename''': the database table name
+  - '''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:'''
+  - '''permit''': check authorization (shortcut for auth.shn_has_permission)
+  - '''_config''': gets a CRUD setting of the target table
+  - '''_view''': finds the pathname of a custom view template
+
+  '''Hooks:'''
+  - '''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:
+
+{{{
+class MyMethodHandler(S3Method):
+
+    def apply_method(r, **attr):
+        return dict()
+}}}
+
+For examples see modules/s3/s3crud.py or modules/s3/s3search.py.