Responses and Presentation

After performing some kind of processing on input information, an application will then want to produce some kind of response to indicate what went on. Here are some examples of responses:

Generating Responses

The procedure involved in generating a response usually involves the following steps:

  1. Setting a response code to signal whether the application performed the requested operation successfully.
  2. Setting a content type and a character encoding.
  3. Possibly setting some response headers.
  4. Producing content and sending it to the user.

The kind of code involved may well resemble the following:

from WebStack.Generic import ContentType

class MyResource:
def respond(self, trans):
[Perform the requested operations.]

if [the operation was successful]:
trans.set_response_code(200)
trans.set_content_type(ContentType("text/html", encoding="utf-8"))
out = trans.get_response_stream()
out.write([some data either as a plain string suitably encoded or as Unicode])
else:
trans.set_response_code(500) # or some other code
trans.set_content_type(ContentType("text/html", encoding="utf-8"))
out = trans.get_response_stream()
out.write([some other data either as a plain string suitably encoded or as Unicode])

Unicode and the Response Stream

Although an encoding may be specified or be set as a default by the EncodingSelector (see "Selectors - Components for Dispatching to Resources"), it should be noted that the encoding of textual information will only take place if Unicode objects are written to the stream. Where binary information or information which should not be changed is being written, this must be supplied as plain strings to the transaction object's write method.

As discussed in "Character Encodings", care must be taken generating the response so that it meets any expectations that browsers and other Web clients may have.

WebStack API - Response-Related Methods

Transaction objects have various methods that can be used in generating responses:

set_response_code
This accepts an integer value denoting the response condition as described in the HTTP specification. If this method is not used, WebStack sets a 200 status condition on the response, meaning that the request was processed successfully.
set_content_type
This accepts a content type object (typically WebStack.Generic.ContentType) which specifies both the media type and the character encoding (if relevant) of the data sent to the user. The media type describes the format of the data (eg. text/html - a Web page), whereas the character encoding describes how any character information on the page is encoded - see "Character Encodings" for more information.
set_header_value
This accepts a header name and a corresponding value. Response headers convey information to the user (and their software) which is comparable to that found in request headers sent in to the Web application; for example, the content type information is transmitted using response headers (using the Content-Type header name), although the above set_content_type method is a more convenient means of preparing such information.
get_response_stream
This returns the output stream through which data may be sent to the user.

Ending the Response Explicitly

Although it is possible to produce some output and then to let the respond function complete normally, sometimes it is appropriate to terminate the response and to hand control straight back to the server environment; in other words, to decide that no more activity will be performed within the application and to send the response immediately. Whilst just using a return statement might be adequate in many applications...

        # In the respond method...
if some_condition:
[Produce a response.]
return
[Produce a different response.]

...sometimes a resource's respond method is being called from another resource, and it may be the case that this other resource may produce additional output if control is returned to it.

To provide a definitive end of response signal, a special exception is available:

from WebStack.Generic import EndOfResponse

[The usual declarations for the resource and the respond method...]

# In the respond method (possibly called by another resource)...
if some_condition:
[Produce a response.]
raise EndOfResponse

This exception, when raised, ensures that the response is sent exactly as the resource intended upon raising the exception. Note that although WebStack.Generic.EndOfResponse is an exception, it will not cause an error condition or change the response code in any way.

Sending the User Elsewhere

Instead of generating any real response, it is also possible to direct an application's user to another resource or application. This is done by performing a "redirect" by sending a special response header to the client, as described in the "Redirection" document.

Integrating with Content Generators

Just as applications might need to integrate with other systems in order to fetch information or to perform operations on behalf of the user, the generation of response content can also be made a lot easier by using external libraries. In the above example code, the process of obtaining and formatting the actual data to be written out has been left unspecified, but for anything more complicated than "hello world" it is usually advisable to consider using templating systems which combine raw data and templates to produce formatted output that can be displayed as a Web page (amongst other things).

See "Integration with Other Systems" for more information on the principles of using such external libraries. See also XSLTools for a distribution of utilities, including a Web forms framework called XSLForms, which can be of use in generating content for Web applications.