Changes between Version 1 and Version 2 of DeveloperGuidelines/Tutorial/RESTCustomisation

Timestamp:

06/11/10 20:58:57 (15 years ago)

Author:

Dominic König

Comment:

--

DeveloperGuidelines/Tutorial/RESTCustomisation

@@ -1 @@
-== REST Customisation ==
+== REST Customisation Mini Tutorial ==
 
 It seems generally difficult for new developers to understand how to take control of functionality in the [wiki:RESTController] of the S3 framework.
@@ -90 +90 @@
 information to process the current REST request, and it is passed to both prep and postp. See [wiki:S3REST#S3RESTRequest] for a list of attributes and methods.
 
-However - there are plenty of possibilities.
-
-Dominic
+Let me give you another recipe:
+
+Imagine you have a resource "warehouse" and want to implement a function "report" that generates a report about the current status of the warehouse.
+
+Now you're gonna provide this report in a RESTful way, i.e. you want to provide it as a resource that can be addressed via URLs like:
+
+{{{
+http://site.myserver.org/eden/wm/warehouse/report
+}}}
+
+and is provided in several different data formats beyond HTML (the interactive view), let's say - XLS and XML:
+
+{{{
+http://site.myserver.org/eden/wm/warehouse/report.xls
+http://site.myserver.org/eden/wm/warehouse/report.xml
+}}}
+
+How to tackle this?
+
+Yes - you can use shn_rest_controller for this!
+
+This could be your "warehouse" controller:
+
+{{{
+def warehouse():
+   """ RESTful CRUD controller """
+   return shn_rest_controller(module, resource, ...)
+}}}
+
+At first you implement your report function (in the controller file). This function takes the argument jr (=S3RESTRequest) and a dict of named arguments (just the same named arguments from the shn_rest_controller call above). This function returns the report. Then, in your controller, you plug in this function to your resource - together it would look like that:
+
+{{{
+def warehouse():
+    """ RESTful CRUD controller """
+    s3xrc.model.set_method(module, resource,
+                     method="report", action=warehouse_report)
+    return shn_rest_controller(module, resource, ...)
+
+def warehouse_report(jr, **attr):
+    """" Warehouse report """
+    <Code to produce the report>
+    return report
+}}}
+
+How to implement the report function now? Well - that's entirely up to you. In case if interactive views, you would usually return a dict of values that 
+are then formatted as HTML in the view template:
+
+{{{
+def warehouse_report(jr, **attr):
+    """" Warehouse report """
+    <Code to produce the report>
+    # Assemble the report as dict:
+    report = dict(title="Page Title", ...)
+    return report
+}}}
+
+Note that if "report" is a dict, then the REST controller automatically adds the S3RESTRequest as "jr" to that dict before returning it. Thus, "jr" is 
+available to the view templates. That also means: do not use "jr" as key in that dict.
+
+However, there may be other formats than HTML - to implement other formats, you might need to check for the representation of the request. This can be 
+found in jr:
+
+{{{
+def warehouse_report(jr, **attr):
+    """" Warehouse report """
+    if jr.representation in ("html", "popup"):
+        <Code to produce the interactive report>
+        # Assemble the report as dict:
+        report = dict(title="Page Title", ...)
+    elif jr.representation == "xls":
+        <Code to produce the XLS report>
+    elif jr.representation in shn_xml_export_formats:
+        <Code to produce the XML report>
+    else:
+        session.error = BADFORMAT
+        redirect(URL(r=jr.request))
+    return report
+}}}
+
+See [wiki:S3REST#S3RESTRequest S3RESTRequest] to find out more about "jr".
+
+To produce the XML report, it is probably sufficient to just export the requested warehouse information in S3XRC-XML, and then use XSLT stylesheets to produce the finally desired XML formats. That's pretty easy:
+
+{{{
+def warehouse_report(jr, **attr):
+    ...
+    elif jr.representation in shn_xml_export_formats:
+        return export_xml(xrequest)
+    ...
+}}}
+
+Perhaps you want to add an RSS feed:
+
+{{{
+def warehouse_report(jr, **attr):
+    ...
+    elif jr.representation == "rss":
+        <Code to produce the RSS report>
+        return report
+    ...
+}}}
+
+Ah - now I forgot to mention how you can get at the data in the warehouse_report example. Your implementation already supports a variety of URLs:
+
+This URL addresses the report for all warehouses:
+{{{
+http://site.myserver.org/eden/wm/warehouse/report
+}}}
+
+This URL addresses the report for the warehouse record with ID=1.
+{{{
+http://site.myserver.org/eden/wm/warehouse/1/report
+}}}
+
+This URL addresses the report in XLS format for the warehouse record with the UUID=123654278 (assuming that you have UUID's in your warehouse table).
+{{{
+http://site.myserver.org/eden/wm/warehouse/report.xls?warehouse.uid=123654278
+}}}
+
+The S3RESTRequest provides the resource information to your warehouse_report function.
+
+In case a specific record has been requested, you can access it as:
+{{{
+    record = jr.record
+}}}
+If jr.record is None, then the request is targeting all warehouse records, so you'd take:
+{{{
+    table = jr.table
+    records = db().select(table.ALL)
+    for record in records:
+       ...
+}}}
+instead.
+
+NOTE: representation in jr is always all lowercase, there is no differentiation between the ".XML" and ".xml" extension in the URL.
+
+And...not to forget:
+
+Your warehouse_report is still a controller function, that means you can implement forms as usual (e.g. operated with form.accepts).
+
+To distinguish between different HTTP methods (in case you need that), you can use:
+
+http_method = jr.http # gives one of "GET", "POST", "PUT" or "DELETE"
+
+(...whatever PUT or DELETE would mean for a warehouse report, you would probably just ignore these)