response

response is another instance of the Storage class. It contains the following:

  • response.body: a StringIO object into which web2py writes the output page body. NEVER CHANGE THIS VARIABLE.
  • response.cookies: similar to request.cookies, but while the latter contains the cookies sent from the client to the server, the former contains cookies sent by the server to the client. The session cookie is handled automatically.
  • response.download(request, db): a method used to implement the controller function that allows downloading of uploaded files. response.download expects the last arg in request.args to be the encoded filename (i.e., the filename generated at upload time and stored in the upload field). It extracts the upload field name and table name as well as the original filename from the encoded filename. response.download takes two optional arguments: chunk_size sets the size in bytes for chunked streaming (defaults to 64K), and attachments determines whether the downloaded file should be treated as an attachment or not (default to True). Note, response.download is specifically for downloading files associated with db upload fields. Use response.stream (see below) for other types of file downloads and streaming. Also, note that it is not necessary to use response.download to access files uploaded to the /static folder — static files can (and generally should) be accessed directly via URL (e.g., /app/static/files/myfile.pdf).
  • response.files: a list of .css, .js, .coffee, and .less files required by the page. They will automatically be linked in the head of the standard “layout.html” via the included “web2py_ajax.html”. To include a new CSS, JS, COFFEE, or LESS file, just append it to this list. It will handle duplicates. The order is important.
  • response.include_files() generates html head tags to include all response.files (used in “views/web2py_ajax.html”).
  • response.flash: optional parameter that may be included in the views. Normally used to notify the user about something that happened.
  • response.headers: a dict for HTTP response headers. Web2py sets some headers by default, including “Content-Length”, “Content-Type”, and “X-Powered-By” (set equal to web2py). Web2py also sets the “Cache-Control”, “Expires”, and “Pragma” headers to prevent client-side caching, except for static file requests, for which client-side caching is enabled. The headers that web2py sets can be overwritten or removed, and new headers can be added (e.g., response.headers['Cache-Control'] = 'private'). You can remove a header by removing its key from the response.headers dict, e.g. del response.headers['Custom-Header'], however web2py’s default headers will be re-added just before returning the response. To avoid this behavior, just set the header value to None, e.g. to remove the default Content-Type header, response.headers['Content-Type'] = None
  • response.menu: optional parameter that may be included in the views, normally used to pass a navigation menu tree to the view. It can be rendered by the MENU helper.
  • response.meta: a Storage object that contains optional <meta> information like response.meta.author, .description, and/or .keywords. The content of each meta variable is automatically placed in the proper META tag by the code in “views/web2py_ajax.html”, which is included by default in “views/layout.html”.
  • response.include_meta() generates a string that includes all response.meta headers serialized (used in “views/web2py_ajax.html”).
  • response.postprocessing: this is a list of functions, empty by default. These functions are used to filter the response object at the output of an action, before the output is rendered by the view. It can be used to implement support for other template languages.
  • response.render(view, vars): a method used to call the view explicitly inside the controller. view is an optional parameter which is the name of the view file, vars is a dictionary of named values passed to the view.
  • response.session_file: file stream containing the session.
  • response.session_file_name: name of the file where the session will be saved.
  • response.session_id: the id of the current session. It is determined automatically. NEVER CHANGE THIS VARIABLE.
  • response.session_id_name: the name of the session cookie for this application. NEVER CHANGE THIS VARIABLE.
  • response.static_version: a version number for the static asset management with response.files.
  • response.static_version_urls: setting this to True enables static asset management on any link to the static folder.
  • response.status: the HTTP status code integer to be passed to the response. Default is 200 (OK).
  • response.stream(file, chunk_size, request=request, attachment=False, filename=None): when a controller returns it, web2py streams the file content back to the client in blocks of size chunk_size. The request parameter is required to use the chunk start in the HTTP header. file should be a file path (for backward compatibility, it can also be an open file object, but this is not recommended). As noted above, response.download should be used to retrieve files stored via an upload field. response.stream can be used in other cases, such as returning a temporary file or StringIO object created by the controller. If attachment is True, the Content-Disposition header will be set to “attachment”, and if filename is also provided, it will be added to the Content-Disposition header as well (but only when attachment is True). If not already included in response.headers, the following response headers will be set automatically: Content-Type, Content-Length, Cache-Control, Pragma, and Last-Modified (the latter three are set to allow browser caching of the file). To override any of these automatic header settings, simply set them in response.headers before calling response.stream.
  • response.subtitle: optional parameter that may be included in the views. It should contain the subtitle of the page.
  • response.title: optional parameter that may be included in the views. It should contain the title of the page and should be rendered inside the html title tag in the header.
  • response.toolbar: a function that allows you to embed a toolbar into page for debugging purposes {{=response.toolbar()}}. The toolbar displays request, response, session variables and database access time for each query.
  • response._vars: this variable is accessible only in a view, not in the action. It contains the values returned by the action to the view.

  • response._caller: this is a function that wraps all action calls. It defaults to the identity function, but it can be modified in order to catch special types of exception to do extra logging;

    1. response._caller = lambda f: f()

  • response.optimize_css: can be set to “concat,minify,inline” to concatenate, minify and inline the CSS files included by web2py.

  • response.optimize_js: can be set to “concat,minify,inline” to concatenate, minify and inline the JavaScript files included by web2py.

  • response.view: the name of the view template that must render the page. This is set by default to:

    1. "%s/%s.%s" % (request.controller, request.function, request.extension)

    or, if the above file cannot be located, to

    1. "generic.%s" % (request.extension)

    Change the value of this variable to modify the view file associated with a particular action.

  • response.delimiters defaults to ('{{','}}'). It allows you to change the delimiter of code embedded in views.
  • response.xmlrpc(request, methods): when a controller returns it, this function exposes the methods via XML-RPC[xmlrpc] . This function is deprecated since a better mechanism is available and described in Chapter 10.
  • response.write(text): a method to write text into the output page body.
  • response.js can contain Javascript code. This code will be executed if and only if the response is received by a web2py component as discussed in Chapter 12.

  • response.models_to_run contains a list of regexes that chooses what models to run.

    • By default, this is set automatically to load /a/models/*.py, /a/models/c/*.py, and /a/models/c/f/*.py files when /a/c/f is requested. You can set, e.g., response.models_to_run = ['myfolder/'] to force the execution only of the models inside your application’s models/myfolder subfolder.
    • NB: response.models_to_run is a list of regex, not a list of filepaths. The regex are relative to the models/ folder, so any model file with a relative file path that matches one of the regexes will be executed. Note also that this can not affect any models which have already been evaluated because they were earlier in the alphabetic sort order. That is, if a conditional model for controller orange was orange/orange_model.py and it set the regex to [.*], that change does not affect any models previously rejected for loading such as the model apple/apple_model.py ; it matches the new regex, but it was evaluated and rejected before orange/orange_model.py changed the regex.
    • This means that if you want to use models_to_run to share conditional models between controllers, put the models in a sub-directory that will sort last such as zzz, and then use a regex ‘zzz’.

Since response is a gluon.storage.Storage object, it can be used to store other attributes that you may want to pass to the view. While there is no technical restriction, our recommendation is to store only variables that are to be rendered by all pages in the overall layout (“layout.html”).

Anyway, we strongly suggest to stick to the variables listed here:

  1. response.title
  2. response.subtitle
  3. response.flash
  4. response.menu
  5. response.meta.author
  6. response.meta.description
  7. response.meta.keywords
  8. response.meta.*

because this will make it easier for you to replace the standard “layout.html” file that comes with web2py with another layout file, one that uses the same set of variables.

Old versions of web2py used response.author instead of response.meta.author and similar for the other meta attributes.