/ 
CatalystX-ASP-1.15
River stage zero No dependents
/ CatalystX::ASP::Response

NAME

CatalystX::ASP::Response - $Response Object

SYNOPSIS

use CatalystX::ASP::Response;

my $resp = CatalystX::ASP::Response->new(asp => $asp);
$resp->Write('<h1>Hello World!</h1>');
my $body = $resp->Body;

DESCRIPTION

This object manages the output from the ASP Application and the client web browser. It does not store state information like the $Session object but does have a wide array of methods to call.

ATTRIBUTES

$Response->{BinaryRef}

API extension. This is a perl reference to the buffered output of the $Response object, and can be used in the Script_OnFlush global.asa event to modify the buffered output at runtime to apply global changes to scripts output without having to modify all the scripts. These changes take place before content is flushed to the client web browser.

sub Script_OnFlush {
  my $ref = $Response->{BinaryRef};
  $$ref =~ s/\s+/ /sg; # to strip extra white space
}
$Response->{CacheControl}

Default "private", when set to public allows proxy servers to cache the content. This setting controls the value set in the HTTP header Cache-Control

$Response->{Charset}

This member when set appends itself to the value of the Content-Type HTTP header. If $Response->{Charset} = 'ISO-LATIN-1' is set, the corresponding header would look like:

Content-Type: text/html; charset=ISO-LATIN-1
$Response->{ContentType}

Default "text/html". Sets the MIME type for the current response being sent to the client. Sent as an HTTP header.

$Response->{Expires}

Sends a response header to the client indicating the $time in SECONDS in which the document should expire. A time of 0 means immediate expiration. The header generated is a standard HTTP date like: "Wed, 09 Feb 1994 22:23:32 GMT".

$Response->{IsClientConnected}

1 if web client is connected, 0 if not. This value starts set to 1, and will be updated whenever a $Response->Flush() is called.

As of Apache::ASP version 2.23 this value is updated correctly before global.asa Script_OnStart is called, so global script termination may be correctly handled during that event, which one might want to do with excessive user STOP/RELOADS when the web server is very busy.

An API extension $Response->IsClientConnected may be called for refreshed connection status without calling first a $Response->Flush

$Response->{Status}

Sets the status code returned by the server. Can be used to set messages like 500, internal server error

METHODS

$Response->AddHeader($name, $value)

Adds a custom header to a web page. Headers are sent only before any text from the main page is sent.

$Response->AppendToLog($message)

Adds $message to the server log. Useful for debugging.

$Response->BinaryWrite($data)

Writes binary data to the client. The only difference from $Response->Write() is that $Response->Flush() is called internally first, so the data cannot be parsed as an html header. Flushing flushes the header if has not already been written.

If you have set the $Response->{ContentType} to something other than text/html, cgi header parsing (see CGI notes), will be automatically be turned off, so you will not necessarily need to use BinaryWrite for writing binary data.

$Response->Clear()

Erases buffered ASP output.

$Response->Cookies($name, [$key,] $value)

Sets the key or attribute of cookie with name $name to the value $value. If $key is not defined, the Value of the cookie is set. ASP CookiePath is assumed to be / in these examples.

$Response->Cookies('name', 'value');
# Set-Cookie: name=value; path=/

$Response->Cookies("Test", "data1", "test value");
$Response->Cookies("Test", "data2", "more test");
$Response->Cookies(
  "Test", "Expires",
  HTTP::Date::time2str(time+86400)
);
$Response->Cookies("Test", "Secure", 1);
$Response->Cookies("Test", "Path", "/");
$Response->Cookies("Test", "Domain", "host.com");
# Set-Cookie:Test=data1=test%20value&data2=more%20test; \
#   expires=Fri, 23 Apr 1999 07:19:52 GMT;              \
#   path=/; domain=host.com; secure

The latter use of $key in the cookies not only sets cookie attributes such as Expires, but also treats the cookie as a hash of key value pairs which can later be accesses by

$Request->Cookies('Test', 'data1');
$Request->Cookies('Test', 'data2');

Because this is perl, you can (though it's not portable!) reference the cookies directly through hash notation. The same 5 commands above could be compressed to:

$Response->{Cookies}{Test} = {
  Secure  => 1,
  Value   => {
    data1 => 'test value',
    data2 => 'more test'
  },
  Expires => 86400, # not portable, see above
  Domain  => 'host.com',
  Path    => '/'
};

and the first command would be:

# you don't need to use hash notation when you are only setting
# a simple value
$Response->{Cookies}{'Test Name'} = 'Test Value';

I prefer the hash notation for cookies, as this looks nice, and is quite perl-ish. It is here to stay. The Cookie() routine is very complex and does its best to allow access to the underlying hash structure of the data. This is the best emulation I could write trying to match the Collections functionality of cookies in IIS ASP.

For more information on Cookies, please go to the source at http://home.netscape.com/newsref/std/cookie_spec.html

$Response->Debug(@args)

API Extension. If the Debug config option is set greater than 0, this routine will write @args out to server error log. Refs in @args will be expanded one level deep, so data in simple data structures like one-level hash refs and array refs will be displayed. CODE refs like

$Response->Debug(sub { "some value" });

will be executed and their output added to the debug output. This extension allows the user to tie directly into the debugging capabilities of this module.

While developing an app on a production server, it is often useful to have a separate error log for the application to catch debugging output separately.

If you want further debugging support, like stack traces in your code, consider doing things like:

$Response->Debug( sub { Carp::longmess('debug trace') };
$SIG{__WARN__} = \&Carp::cluck; # then warn() will stack trace

The only way at present to see exactly where in your script an error occurred is to set the Debug config directive to 2, and match the error line number to perl script generated from your ASP script.

However, as of version 0.10, the perl script generated from the asp script should match almost exactly line by line, except in cases of inlined includes, which add to the text of the original script, pod comments which are entirely yanked out, and <% # comment %> style comments which have a \n added to them so they still work.

$Response->End()

Sends result to client, and immediately exits script. Automatically called at end of script, if not already called.

$Response->Flush()

Sends buffered output to client and clears buffer.

$Response->Include($filename, @args)

This API extension calls the routine compiled from asp script in $filename with the args @args. This is a direct translation of the SSI tag

<!--#include file=$filename args=@args-->

Please see the SSI section for more on SSI in general.

This API extension was created to allow greater modularization of code by allowing includes to be called with runtime arguments. Files included are compiled once, and the anonymous code ref from that compilation is cached, thus including a file in this manner is just like calling a perl subroutine. The @args can be found in @_ in the includes like:

# include.inc
<% my @args = @_; %>

As of 2.23, multiple return values can be returned from an include like:

my @rv = $Response->Include($filename, @args);
$Response->Include(\$script_text, @args)

Added in Apache::ASP 2.11, this method allows for executing ASP scripts that are generated dynamically by passing in a reference to the script data instead of the file name. This works just like the normal $Response->Include() API, except a string reference is passed in instead of a filename. For example:

<%
  my $script = "<\% print 'TEST'; %\>";
  $Response->Include(\$script);
%>

This include would output TEST. Note that tokens like <% and %> must be escaped so Apache::ASP does not try to compile those code blocks directly when compiling the original script. If the $script data were fetched directly from some external resource like a database, then these tokens would not need to be escaped at all as in:

<%
  my $script = $dbh->selectrow_array(
     "select script_text from scripts where script_id = ?",
     undef, $script_id
     );
  $Response->Include(\$script);
%>

This method could also be used to render other types of dynamic scripts, like XML docs using XMLSubs for example, though for complex runtime XML rendering, one should use something better suited like XSLT.

$Response->IsClientConnected()

API Extension. 1 for web client still connected, 0 if disconnected which might happen if the user hits the stop button. The original API for this $Response->{IsClientConnected} is only updated after a $Response->Flush is called, so this method may be called for a refreshed status.

Note $Response->Flush calls $Response->IsClientConnected to update $Response->{IsClientConnected} so to use this you are going straight to the source! But if you are doing a loop like:

while(@data) {
  $Response->End if ! $Response->{IsClientConnected};
  my $row = shift @data;
  %> <%= $row %> <%
  $Response->Flush;
}

Then its more efficient to use the member instead of the method since $Response->Flush() has already updated that value for you.

$Response->Redirect($url)

Sends the client a command to go to a different url $url. Script immediately ends.

$Response->TrapInclude($file, @args)

Calls $Response->Include() with same arguments as passed to it, but instead traps the include output buffer and returns it as as a perl string reference. This allows one to postprocess the output buffer before sending to the client.

my $string_ref = $Response->TrapInclude('file.inc');
$$string_ref =~ s/\s+/ /sg; # squash whitespace like Clean 1
print $$string_ref;

The data is returned as a referenece to save on what might be a large string copy. You may dereference the data with the $$string_ref notation.

$Response->Write($data)

Write output to the HTML page. <%=$data%> syntax is shorthand for a $Response->Write($data). All final output to the client must at some point go through this method.

SEE ALSO