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.

$generator = Contentment::Response->error($exception)

$generator = Contentment::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 = Contentment::Response->redirect($url)

$generator = Contentment::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 = Contentment::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 = Contentment::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

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

$test = Contentment::Response->header_sent

Contentment::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 = Contentment::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 = Contentment::Response->top_kind

Contentment::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 = Contentment::Response->generator

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

HOOKS

Contentment::Resposne::begin

Handlers of this hook can expect no arguments, but their output will be captured and passed on to the generator. It runs right before generator.

Contentment::Response:end

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::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::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.