Changes between Version 36 and Version 37 of S3REST


Ignore:
Timestamp:
05/14/10 07:33:01 (12 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3REST

    v36 v37  
    7777
    7878The ''action'' method has to take the same arguments as the default handlers: ''jr'' (S3RESTRequest) and ''**attr''.
     79
     80== Pre- and Post-Hooks ==
     81
     82You can hook in a '''preprocessing''' function into the REST controller (as response.s3.prep) which will be called ''after'' the controller has parsed the request, but ''before'' it gets actually executed - with the current S3RESTRequest as argument (which includes the primary resource record, if any).
     83
     84This allows you to easily make changes to resource settings (e.g. access control, list fields etc.), or even to the REST controller configuration (e.g. custom methods) depending on the request type, its parameters or the addressed resource, without having to parse the web2py request manually. You can even bypass the execution of the request and thus hook in your own REST controller - with the advantage that you don't need to parse the request anymore.
     85
     86A simple example:
     87
     88Original code fragment:
     89{{{
     90if len(request.args) == 0:
     91    # List View - reduce fields to declutter
     92    table.message.readable = False
     93    table.categories.readable = False
     94    table.verified_details.readable = False
     95    table.actioned_details.readable = False
     96
     97    response.s3.pagination = True #enable SSPag here!
     98
     99    return shn_rest_controller(module, resource, listadd=False)
     100}}}
     101
     102Using the pre-processor hook instead:
     103{{{
     104    def log_prep(jr):
     105        if jr.representation=="html" and \
     106           jr.method is None and \
     107           jr.component is None:
     108            # Log listing - reduce fields to declutter
     109            table.message.readable = False
     110            table.categories.readable = False
     111            table.verified_details.readable = False
     112            table.actioned_details.readable = False
     113        return True
     114
     115    response.s3.prep = log_prep
     116    response.s3.pagination = True #enable SSPag here!
     117
     118    return shn_rest_controller(module, resource, listadd=False)
     119}}}
     120
     121The return value of the preprocessor function can simply be True, in which case the REST request will be executed as usual. Returning False would lead to a HTTP400 "Invalid Request" exception being raised.
     122
     123The return value of the preprocessor function can also be a dict for more granular control - containing the following elements (all optional):
     124
     125 - '''success''': boolean (default: True)
     126 - '''output''': dict (default: None)
     127 - '''bypass''': boolean (default: False)
     128
     129If ''bypass'' is True, then the REST controller does not execute the request (the post-hook is executed, though). ''output'' must not be None in this case - it will be returned from the REST controller.
     130
     131If ''success'' is False, and ''output'' is not None, then the REST controller does not execute the request, but just returns "output" (post-hook will ''not'' be executed in this case).
     132
     133If ''success'' is False and ''output'' is None, a HTTP400 "Invalid Request" will be raised instead.
     134
     135Examples:
     136
     137In most cases, you will just return "True" - in some cases you might want to raise an error, e.g.:
     138{{{
     139    response.error = "This request cannot be executed"
     140    return dict(
     141        success=False,
     142        output=dict(title="My Pagetitle", item="Sorry, no data..."))
     143}}}
     144
     145There is also a '''post-processing hook''' (response.s3.postp) that allows you to execute something directly after the REST request has been executed, but before the shn_rest_controller returns. The post-hook function will be called with the current S3RESTRequest and the output dict of its execution as arguments.
     146
    79147== S3RESTRequest ==
    80148