NAME

Contentment::Response - Handles Contentment response handling

DESCRIPTION

This is the class responsible for outputting the responses to a request. It provides an API for manipulating that output, such as specifying additional headers to output, specifying the MIME type, status, etc.

$response = $context->response

Before you can do anything, you call any of these methods, you will need to retrieve the response object from the context. This object will be available as soon just before the "Contentment::Response::begin" hook is called and remains available until immediately after the call to "Contentment::Response::end".

$generator = $response->error($exception)

$generator = $response->error($status, $message, $description, $detail)

When called, it will use the "Contentment::Response::error" hook to attempt to locate a handler capable of handling the error message. The first form simply names an error message, $exception, to print. This method will always return a generator object (i.e., if none of the hook handlers return one or there aren't any handlers, the method will create one).

The second form allows for more fine grained control. The $status is the numeric HTTP error code to return and the $message is a short named description of the error. The $description is a longer descriptive text and $detail is debug information that probably ought not be displayed to the user (or not directly).

All arguments are optional.

$generator = $response->redirect($url)

$generator = $response->redirect($url, %query)

This method is given a URL and will create a generator that returns a temporary redirect to that URL. The $url may either be a URI object or a string. The URL may be either absolute or relative. If the URL is relative, it will be converted to an absolute address using the base_url() method of the current Contentment::Site, thus the address should be relative to the current root path.

If you wish, you may also add a set of query variables on the end of the list. These will be appended to the URL following a "?" and will be formatted and escaped for you.

$generator = $response->resolve($path)

This returns the generator that would be used to give a response for the given path, $path. If no $path is given, it will default to the path_info of the CGI object.

This method always returns a generator. If no generator is found using the "Contentment::Response::resolve" hook or an error occurs during the process, then the error method is called to return a "Not Found" document. You can check for that circumstance as follows:

  my $generator = $ctx->response->resolve($some_path);
  if ($generator->get_property('error')) {
      # It's an error document
  } else {
          # It's the document we requested
  }

Contentment::Response->handle_cgi($ctx)

This should not be called outside of a Contentment handler method. It returns the completed response.

$test = $response->header_sent

$response->header_sent($header_sent)

Returns a true value if the headers were already printed as part of the request. Set to a true value if you send headers. Once set to true, it cannot be set back to false.

$header = $response->header

Returns a reference to a hash to store header information in. This hash will be passed to the CGI header function.

$top_kind = $response->top_kind

$response->top_kind($kind)

Used to reflect the current file kind of the top level response. This should be initially set during content generation by a call to the generated_kind method of the file type plugin generating the output. It, then, may be modified further by later filters. It starts with an initial value of the empty string "".

$generator = $response->generator

This is used to fetch the top-most generator for the request.

CONTEXT

This package adds the following context methods:

$response = $context->response

This returns the current response object for the response being generated. It is only valid during and between the "Contentment::Response::begin" and "Contentment::Response::filter" hooks.

HOOKS

Contentment::Response::resolve

These handlers take a path argument and should ultimately result in in a generator object (see Contentment::Generator). The result of the previous handler is passed as the argument to the next.

Contentment::Resposne::begin

Handlers of this hook can expect just the context as an argument. The output of these hooks will be captured and passed on to the generator. It runs right before generator.

Contentment::Response:filter

These handlers will be given the current context as an argument. Handlers of this hook can expect the input from the generated output or the previous handler's output. The output will be captured for output to the client.

Contentment::Response::end

Handlers of this hook can expect just the context as an argument. No special input is given and they should output nothing. This gives handlers one last shot to modify the the non-content aspects of the response (such as headers).

Contentment::Response::error

These handlers take the four arguments that the error method accepts and should return either undef or a generator object (see Contentment::Generator) capable of returning an error page.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is distributed and licensed under the same terms as Perl itself.