Changes between Version 79 and Version 80 of S3/S3REST/s3_rest_controller

Timestamp:

06/04/13 21:07:53 (12 years ago)

Author:

hardik juneja

Comment:

--

S3/S3REST/s3_rest_controller

@@ -505 +505 @@
 === Custom Methods ===
 
+If 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'''
+
+you can use s3_rest_controller for this!
+
+This could be your "warehouse" CRUD controller:
+
+{{{
+def warehouse():
+
+   """ RESTful CRUD controller """
+
+   return s3_rest_controller(module, resource, ...)
+}}}
+
+At first you implement your report function (in the controller file). This function takes the argument r (=S3RESTRequest) and a dict of named arguments (just the same named arguments from the s3_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+Reports controller """
+
+    # Plug warehouse_report into warehouse resource:
+    s3db.set_method(module, resource, method="report", action=warehouse_report)
+
+    return shn_rest_controller(module, resource, ...)
+
+def warehouse_report(r, **attr):
+
+    """ Warehouse report generator """
+
+    # Code to produce the report goes here
+    report = ...
+
+    return report
+}}}
+
+Note that if "report" is a dict, then the REST controller automatically adds the S3Request as "r" to that dict before returning it. Thus, "r" is 
+available to the view templates. That also means: do not use "r" 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 r:
+
+{{{
+def warehouse_report(r, **attr):
+
+    """ Warehouse report generator """
+
+    if r.representation in ("html", "popup"):
+        # Code to produce the report items:
+        title = T("Warehouse Report")
+
+        # Assemble the report items in a dict:
+        report = dict(title=title, ...)
+
+    elif r.representation == "xls":
+        # Code to produce the XLS report goes here
+        ...
+
+    elif r.representation in s3_xml_export_formats:
+        # Code to produce the XML report goes here
+        ...
+
+    else:
+        r.error(501, r.ERROR.BAD_FORMAT)
+
+    return report
+}}}
+
+See [wiki:S3XRC#RESTfulAPI#S3Request S3Request] to find out more about "r".
+
+To produce the XML report, it is probably sufficient to just export the requested warehouse information in S3-XML, and then use XSLT stylesheets to produce the finally desired XML formats. That's pretty easy:
+
+{{{
+def warehouse_report(r, **attr):
+    ...
+    elif r.representation in s3_xml_export_formats:
+        report = export_xml(xrequest)
+    ...
+}}}
+
+Perhaps you want to add an RSS feed:
+
+{{{
+def warehouse_report(r, **attr):
+    ...
+    elif r.representation == "rss":
+        # Code to produce the RSS report goes here
+        report = ...
+    ...
+}}}
+
+Getting the data from the warehouse_report.
+
+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 S3Request provides the resource information to your warehouse_report function.
+
+In case a specific record has been requested, you can access it as:
+{{{
+    record = r.record
+}}}
+If r.record is None, then the request is targeting all warehouse records, so you'd take:
+{{{
+    table = r.table
+    records = db().select(table.ALL)
+    for record in records:
+       ...
+}}}
+instead.
+
+NOTE: representation in r 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 or web2py Crud).
+
+
 ----