NAME

CGI::Response - Respond to CGI requests

SYNOPSIS

Simple Interface

  use CGI::Response qw(:Simple);
  print ContentType;
  print "<html><head>\n"; # .....

Full Interface

  use CGI::Response;
  $response = new CGI::Response;
  $response->content_type;
  print $response->as_string;
  print "<html><head>\n"; # .....

DESCRIPTION

CGI::Response is a Perl5 module for constructing responses to Common Gateway Interface (CGI) requests. It is designed to be light-weight and efficient for the most common tasks, and also to provide access to all HTTP response features for more advanced CGI applications.

There are two ways to use CGI::Response. For basic applications, the Simple Interface provides a number of plain functions that cover the most commonly-used CGI response headers. More advanced applications may employ the Full Interface object methods to access any HTTP header, or to add experimental or non-standard headers. Both interfaces try to generate reasonable defaults whenever possible.

For efficiency, just the Simple Interface functions are compiled on start-up. Full Interface methods are compiled only when they are called. This helps to make CGI::Response usable in a variety of applications. [See SelfLoader for more information.]

Simple Interface

The Simple Interface methods are not exported by default. In order to use them, you must import them explicitly. You can import all of the methods at once by saying:

   use CGI::Response qw(:Simple);

Or, you can import just one function by listing it by name, as in:

   use CGI::Response qw(ContentType);

Only one Simple Interface function should be called in a response, since all of these functions terminate the response header (that is, send the blank line denoting the end of the header) immediately upon execution. If you need to use a combination of headers not provided by the Simple Interface, use the Full Interface instead.

All of the Simple Interface functions force a flush on the currently-selected output channel (that is, they set "$| = 1"). This is done to prevent a common probelm in CGI scripts, where a system() or exec() call causes output before the response header, and generates a server error. If you do not want "$| = 1", you should either set it back to 0 after using the Simple Interface, or you should employ the Full Interface, which does not have this side effect.

For reference, below is a list of the headers sent by each function, and the default header values, if any. Arguments are listed in the order they should appear. Square brackets ([]) indicate optional arguments; angled brackets (<>) indicate required arguments.

   Function      Argument(s)      Header(s)      Default(s)
   --------      -----------      ---------      ----------
   &ContentType  [content-type]   Content-Type   text/html
   &Redirect     <Location/URI>   Location       [none]
                 [permanent?]     URI            [none]
                                  Content-Type   text/html
                                  Status         302 Moved Temporarily
   &NoCache      [content-type]   Content-Type   text/html
                                  Pragma         no-cache
                                  Expires        [now]
   &NoContent                     Status         204 No Content

Each of these functions is documented more completely below, and examples for each are provided.

&ContentType

This is the most commonly-used function. It identifies the Internet Media Type of the entity that follows. If you call it without an argument, it will send "text/html" as the content-type.

   use CGI::Response qw(:Simple);
   print &ContentType;   # defaults to text/html

Otherwise, you can specify some other content-type:

   use CGI::Response qw(:Simple);
   print &ContentType('image/gif');

This function should be called as early as possible to prevent server errors (see the note on $| above).

&Redirect

A redirect causes the user-agent to make a follow-up request for some other resource. Some user-agents will be better than others at complying with a redirect, so this function tries to be as explicit as possible.

You are required to give one argument, specifying the URL which the user-agent should request. A second argument is accepted as a Boolean value -- if any second argument is present, the browser will be told that the requested resource has moved permanently to a new URL (that is, future requests for the document should be to the new URL, not to the one which was first requested).

   use CGI::Response qw(:Simple);
   print &Redirect('http://www.company.com/', 'permanent');
   # this resource has moved permanently, status 301

If no second argument is given, the redirect will be specified as temporary.

   use CGI::Response qw(:Simple);
   print &Redirect('http://www.company.com/');   
   # this resource has moved temporarily, status 302

A brief HTML page is output after the header so that users whose user-agents fail to recognize the redirect will get an informative message with a link to the redirect. Use the Full Interface to supply some other page or none at all.

&NoCache

This function tries to inform user-agents and proxy servers that the included resource should not be cached. It does so by sending both an "Expires" header, set for immediate expiration, and a "Pragma: no-cache" header, which older user-agents and servers might not recognize.

Preventing caching is important to CGI applications which produce output based on some factor of the request (such as which user-agent made the request). For instance, a shopping-basket application would not want to allow caching of an order information page, which may contain user-specific information.

It must be noted, however, that caches prevent excess network load and cache-friendly applications are always preferable to use of the &NoCache function. This function should only be used when there is no other alternative.

&NoCache takes one optional argument, the content-type of the entity to follow. Therefore, its call is nearly identical to the &ContentType function, and the two functions may be interchanged easily. As with &ContentType, if you call &NoCache without an argument, it will send "text/html" as the content-type.

   use CGI::Response qw(:Simple);
   print &NoCache;   # defaults to text/html

Otherwise, you can specify some other content-type:

   use CGI::Response qw(:Simple);
   print &NoCache('image/gif');

As noted earlier, this function should be called as early as possible to prevent server errors (see the note on $| above).

&NoContent

&NoContent allows a script to accept input without changing the current page in the user-agent's view. This may be useful for a successful form input that requires no response, or for an imagemap click that does not have a defined link.

A No Content response does not reset form fields after submission. HTTP/1.1 will include a "205 Reset Document" status for this purpose, and a future version of this module will provide a &Reset function to support this status.

This function sends only one header, "Status: 204 No Content", and it takes no arguments.

   use CGI::Response qw(:Simple);
   print &NoContent;

Full Interface

The Full Interface is still under development and is not currently documented.

DEPENDENCIES

NOTES

Please note that future versions are not guaranteed to be backwards-compatible with this version. The interface will be frozen at version 0.1 (first beta release).

VERSION

  Version:      0.03 (alpha release)
  Release date: 02 December 1995

AUTHOR

  Marc Hedlund <hedlund@best.com>
  Copyright 1995, All rights reserved