NAME
CGI::Portable::Response - Stores user output; HTTP headers/body, HTML page pieces
DEPENDENCIES
Perl Version
5.004Standard Modules
I<none>Nonstandard Modules
HTML::EasyTags 1.06 -- only required in page_as_string()SYNOPSIS
See CGI::Portable, which is a subclass of this.
DESCRIPTION
This class is designed to be inherited by CGI::Portable and implements some of that module's functionality; however, this class can also be used by itself. The split of functionality between several modules is intended to emphasize the fact that CGI::Portable is doing several tasks in parallel that are related but distinct, so you have more flexability to use what you need and not carry around what you don't use. Each module has the POD for all methods it implements.
This class is designed to accumulate and assemble the components of an HTTP response, complete with status code, content type, other headers, and a body. The intent is for your core program to use these to store its user output, and then your thin program config shell would actually send the page to the user. These properties are initialized with values suitable for returning an HTML page.
Half of the functionality in this class is specialized for HTML responses, which are assumed to be the dominant activity. This class is designed to accumulate and assemble the components of a new HTML page, complete with body, title, meta tags, and cascading style sheets. HTML assembly is done with the page_as_string() method.
The "http body" property is intended for use when you want to return raw content of any type, whether it is text or image or other binary. It is a complement for the html assembling methods and should be left undefined if they are used.
SYNTAX
This class does not export any functions or methods, so you need to call them using object notation. This means using Class->function() for functions and $object->method() for methods. If you are inheriting this class for your own modules, then that often means something like $self->method().
CONSTRUCTOR FUNCTIONS AND METHODS AND CONTEXT SWITCHING
These functions and methods are involved in making new CGI::Portable::Response objects, except the last one which combines two existing ones. All five of them are present in both CGI::Portable and other classes designed to be inherited by it, including this one, because they implement its functionality.
new()
This function creates a new CGI::Portable::Response (or subclass) object and returns it.
initialize()
This method is used by new() to set the initial properties of objects that it creates.
clone([ CLONE ])
This method initializes a new object to have all of the same properties of the current object and returns it. This new object can be provided in the optional argument CLONE (if CLONE is an object of the same class as the current object); otherwise, a brand new object of the current class is used. Only object properties recognized by CGI::Portable::Response are set in the clone; other properties are not changed.
make_new_context([ CONTEXT ])
This method initializes a new object of the current class and returns it. This new object has some of the current object's properties, namely the "input" properties, but lacks others, namely the "output" properties; the latter are initialized to default values instead. As with clone(), the new object can be provided in the optional argument CONTEXT (if CONTEXT is an object of the same class); otherwise a brand new object is used. Only properties recognized by CGI::Portable::Response are set in this object; others are not touched.
take_context_output( CONTEXT[, LEAVE_SCALARS[, REPLACE_LISTS]] )
This method takes another CGI::Portable::Response (or subclass) object as its CONTEXT argument and copies some of its properties to this object, potentially overwriting any versions already in this object. If CONTEXT is not a valid CGI::Portable::Response (or subclass) object then this method returns without changing anything. The properties that get copied are the "output" properties that presumably need to work their way back to the user. In other words, this method copies everything that make_new_context() did not. This method will never copy any properties which are undefined scalars or empty lists, so a CONTEXT with no "output" properties set will not cause any changes. If any scalar output properties of CONTEXT are defined, they will overwrite any defined corresponding properties of this object by default; however, if the optional boolean argument LEAVE_SCALARS is true, then the scalar values are only copied if the ones in this object are not defined. If any list output properties of CONTEXT have elements, then they will be appended to any corresponding ones of this object by default, thereby preserving both (except with hash properties, where like hash keys will overwrite); however, if the optional boolean argument REPLACE_LISTS is true, then any existing list values are overwritten by any copied CONTEXT equivalents.
METHODS FOR MAKING NEW HTTP RESPONSES
These methods are designed to accumulate and assemble the components of an HTTP response, complete with status code, content type, other headers, and a body. See the DESCRIPTION for more details.
http_status_code([ VALUE ])
This method is an accessor for the "status code" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. This property is used in a new HTTP header to give the result status of the HTTP request that this program is serving. It defaults to "200 OK" which means success and that the HTTP body contains the document they requested. Unlike other HTTP header content, this property is special and must be the very first thing that the HTTP server returns, on a line like "HTTP/1.0 200 OK". However, the property also may appear elsewhere in the header, on a line like "Status: 200 OK".
http_window_target([ VALUE ])
This method is an accessor for the "window target" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. This property is used in a new HTTP header to indicate which browser window or frame that this this HTTP response should be loaded into. It defaults to the undefined value, meaning this response ends up in the same window/frame as the page that called it. This property would be used in a line like "Window-Target: leftmenu".
http_content_type([ VALUE ])
This method is an accessor for the "content type" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. This property is used in a new HTTP header to indicate the document type that the HTTP body is, such as text or image. It defaults to "text/html" which means we are returning an HTML page. This property would be used in a line like "Content-Type: text/html".
http_redirect_url([ VALUE ])
This method is an accessor for the "redirect url" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. This property is used in a new HTTP header to indicate that we don't have the document that the user wants, but we do know where they can get it. If this property is defined then it contains the url we redirect to. This property would be used in a line like "Location: http://www.cpan.org".
get_http_cookies_ref()
This method is an accessor for the "http cookies" array property of this object, a reference to which it returns. Cookies are used for simple data persistance on the client side, and are passed back and forth in the HTTP headers. If this property is defined, then a "Set-Cookie" HTTP header would be made for each list element. Each array element is treated like a scalar internally as this class assumes you will encode each cookie prior to insertion.
get_http_cookies()
This method returns a list containing "http cookies" list elements. This list is returned literally in list context and as an array ref in scalar context.
set_http_cookies( VALUE )
This method allows you to set or replace the current "http cookies" list with a new one. The argument VALUE can be either an array ref or scalar or literal list.
add_http_cookies( VALUES )
This method will take a list of encoded cookies in the argument VALUES and append them to the internal "http cookies" list property. VALUES can be either an array ref or a literal list.
get_http_headers_ref()
This method is an accessor for the "misc http headers" hash property of this object, a reference to which it returns. HTTP headers constitute the first of two main parts of an HTTP response, and says things like the current date, server type, content type of the document, cookies to set, and more. Some of these have their own methods, above, if you wish to use them. Each key/value pair in the hash would be used in a line like "Key: value".
get_http_headers([ KEY ])
This method allows you to get the "misc http headers" hash property of this object. If KEY is defined then it is taken as a key in the hash and the associated value is returned. If KEY is not defined then the entire hash is returned as a list; in scalar context this list is in a new hash ref.
set_http_headers( KEY[, VALUE] )
This method allows you to set the "misc http headers" hash property of this object. If KEY is a valid HASH ref then all the existing headers information is replaced with the new hash keys and values. If KEY is defined but it is not a Hash ref, then KEY and VALUE are inserted together into the existing hash.
add_http_headers( KEY[, VALUE] )
This method allows you to add key/value pairs to the "misc http headers" hash property of this object. If KEY is a valid HASH ref then the keys and values it contains are inserted into the existing hash property; any like-named keys will overwrite existing ones, but different-named ones will coexist. If KEY is defined but it is not a Hash ref, then KEY and VALUE are inserted together into the existing hash.
http_body([ VALUE ])
This method is an accessor for the "http body" scalar property of this object, which it returns. This contitutes the second of two main parts of an HTTP response, and contains the actual document that the user will view and/or can save to disk. If this property is defined, then it will be used literally as the HTTP body part of the output. If this property is not defined then a new HTTP body of type text/html will be assembled out of the various "page *" properties instead. This property defaults to undefined.
http_body_is_binary([ VALUE ])
This method is an accessor for the "http body is binary" boolean property of this object, which it returns. If VALUE is defined, this property is set to it. If this property is true then it indicates that the HTTP body is binary and should be output with binmode on. It defaults to false.
METHODS FOR MAKING NEW HTML PAGES
These methods are designed to accumulate and assemble the components of a new HTML page, complete with body, title, meta tags, and cascading style sheets. See the DESCRIPTION for more details.
page_prologue([ VALUE ])
This method is an accessor for the "page prologue" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. This property is used as the very first thing in a new HTML page, appearing above the opening <HTML> tag. The property starts out undefined, and unless you set it then the default proglogue tag defined by HTML::EasyTags is used instead. This property doesn't have any effect unless your HTML::EasyTags is v1-06 or later.
page_title([ VALUE ])
This method is an accessor for the "page title" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. This property is used in the header of a new HTML document to define its title. Specifically, it goes between a <TITLE></TITLE> tag pair.
page_author([ VALUE ])
This method is an accessor for the "page author" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. This property is used in the header of a new HTML document to define its author. Specifically, it is used in a new '<LINK REV="made">' tag if defined.
get_page_meta_ref()
This method is an accessor for the "page meta" hash property of this object, a reference to which it returns. Meta information is used in the header of a new HTML document to say things like what the best keywords are for a search engine to index this page under. Each key/value pair in the hash would have a '<META NAME="k" VALUE="v">' tag made out of it.
get_page_meta([ KEY ])
This method allows you to get the "page meta" hash property of this object. If KEY is defined then it is taken as a key in the hash and the associated value is returned. If KEY is not defined then the entire hash is returned as a list; in scalar context this list is in a new hash ref.
set_page_meta( KEY[, VALUE] )
This method allows you to set the "page meta" hash property of this object. If KEY is a valid HASH ref then all the existing meta information is replaced with the new hash keys and values. If KEY is defined but it is not a Hash ref, then KEY and VALUE are inserted together into the existing hash.
add_page_meta( KEY[, VALUE] )
This method allows you to add key/value pairs to the "page meta" hash property of this object. If KEY is a valid HASH ref then the keys and values it contains are inserted into the existing hash property; any like-named keys will overwrite existing ones, but different-named ones will coexist. If KEY is defined but it is not a Hash ref, then KEY and VALUE are inserted together into the existing hash.
get_page_style_sources_ref()
This method is an accessor for the "page style sources" array property of this object, a reference to which it returns. Cascading Style Sheet (CSS) definitions are used in the header of a new HTML document to allow precise control over the appearance of of page elements, something that HTML itself was not designed for. This property stores urls for external documents having stylesheet definitions that you want linked to the current document. If this property is defined, then a '<LINK REL="stylesheet" SRC="url">' tag would be made for each list element.
get_page_style_sources()
This method returns a list containing "page style sources" list elements. This list is returned literally in list context and as an array ref in scalar context.
set_page_style_sources( VALUE )
This method allows you to set or replace the current "page style sources" definitions. The argument VALUE can be either an array ref or literal list.
add_page_style_sources( VALUES )
This method will take a list of "page style sources" definitions and add them to the internally stored list of the same. VALUES can be either an array ref or a literal list.
get_page_style_code_ref()
This method is an accessor for the "page style code" array property of this object, a reference to which it returns. Cascading Style Sheet (CSS) definitions are used in the header of a new HTML document to allow precise control over the appearance of of page elements, something that HTML itself was not designed for. This property stores CSS definitions that you want embedded in the HTML document itself. If this property is defined, then a "<STYLE><!-- code --></STYLE>" multi-line tag is made for them.
get_page_style_code()
This method returns a list containing "page style code" list elements. This list is returned literally in list context and as an array ref in scalar context.
set_page_style_code( VALUE )
This method allows you to set or replace the current "page style code" definitions. The argument VALUE can be either an array ref or literal list.
add_page_style_code( VALUES )
This method will take a list of "page style code" definitions and add them to the internally stored list of the same. VALUES can be either an array ref or a literal list.
get_page_head_ref()
This method is an accessor for the "page head" array property of this object, a reference to which it returns. While this property actually represents a scalar value, it is stored as an array for possible efficiency, considering that new portions may be appended or prepended to it as the program runs. This property is inserted between the "<HEAD></HEAD>" tags of a new HTML page, following any other properties that go in that section.
get_page_head()
This method returns a string of the "page body" joined together.
set_page_head( VALUE )
This method allows you to set or replace the current "page head" with a new one. The argument VALUE can be either an array ref or scalar or literal list.
append_page_head( VALUE )
This method allows you to append content to the current "page head". The argument VALUE can be either an array ref or scalar or literal list.
prepend_page_head( VALUE )
This method allows you to prepend content to the current "page head". The argument VALUE can be either an array ref or scalar or literal list.
get_page_frameset_attributes_ref()
This method is an accessor for the "page frameset attributes" hash property of this object, a reference to which it returns. Each key/value pair in the hash would become an attribute key/value of the opening <FRAMESET> tag of a new HTML document. At least it would if this was a frameset document, which it isn't by default. If there are multiple frames, then this property says how the browser window is partitioned into a grid with one or more rows and one or more columns of frames. Valid attributes include 'rows => "*,*,..."', 'cols => "*,*,..."', and 'border => nn'. See also the http_window_target() method.
get_page_frameset_attributes([ KEY ])
This method allows you to get the "page frameset attributes" hash property of this object. If KEY is defined then it is taken as a key in the hash and the associated value is returned. If KEY is not defined then the entire hash is returned as a list; in scalar context this list is in a new hash ref.
set_page_frameset_attributes( KEY[, VALUE] )
This method allows you to set the "page frameset attributes" hash property of this object. If KEY is a valid HASH ref then all the existing attrib information is replaced with the new hash keys and values. If KEY is defined but it is not a Hash ref, then KEY and VALUE are inserted together into the existing hash.
add_page_frameset_attributes( KEY[, VALUE] )
This method allows you to add key/value pairs to the "page frameset attributes" hash property of this object. If KEY is a valid HASH ref then the keys and values it contains are inserted into the existing hash property; any like-named keys will overwrite existing ones, but different-named ones will coexist. If KEY is defined but it is not a Hash ref, then KEY and VALUE are inserted together into the existing hash.
get_page_frameset_refs()
This method is an accessor for the "page frameset" array property of this object, a list of references to whose elements it returns. Each property element is a hash ref which contains attributes for a new <FRAME> tag. This property is inserted between the "<FRAMESET></FRAMESET>" tags of a new HTML page.
get_page_frameset()
This method returns a list of frame descriptors from the "page frameset" property.
set_page_frameset( VALUE )
This method allows you to set or replace the current "page frameset" list with a new one. The argument VALUE can be either an array ref or scalar or literal list.
append_page_frameset( VALUE )
This method allows you to append frame descriptors to the current "page frames". The argument VALUE can be either an array ref or scalar or literal list.
prepend_page_frameset( VALUE )
This method allows you to prepend frame descriptors to the current "page frames". The argument VALUE can be either an array ref or scalar or literal list.
get_page_body_attributes_ref()
This method is an accessor for the "page body attributes" hash property of this object, a reference to which it returns. Each key/value pair in the hash would become an attribute key/value of the opening <BODY> tag of a new HTML document. With the advent of CSS there wasn't much need to have the BODY tag attributes, but you may wish to do this for older browsers. In the latter case you could use body attributes to define things like the page background color or picture.
get_page_body_attributes([ KEY ])
This method allows you to get the "page body attributes" hash property of this object. If KEY is defined then it is taken as a key in the hash and the associated value is returned. If KEY is not defined then the entire hash is returned as a list; in scalar context this list is in a new hash ref.
set_page_body_attributes( KEY[, VALUE] )
This method allows you to set the "page body attributes" hash property of this object. If KEY is a valid HASH ref then all the existing attrib information is replaced with the new hash keys and values. If KEY is defined but it is not a Hash ref, then KEY and VALUE are inserted together into the existing hash.
add_page_body_attributes( KEY[, VALUE] )
This method allows you to add key/value pairs to the "page body attributes" hash property of this object. If KEY is a valid HASH ref then the keys and values it contains are inserted into the existing hash property; any like-named keys will overwrite existing ones, but different-named ones will coexist. If KEY is defined but it is not a Hash ref, then KEY and VALUE are inserted together into the existing hash.
get_page_body_ref()
This method is an accessor for the "page body" array property of this object, a reference to which it returns. While this property actually represents a scalar value, it is stored as an array for possible efficiency, considering that new portions may be appended or prepended to it as the program runs. This property is inserted between the "<BODY></BODY>" tags of a new HTML page.
get_page_body()
This method returns a string of the "page body" joined together.
set_page_body( VALUE )
This method allows you to set or replace the current "page body" with a new one. The argument VALUE can be either an array ref or scalar or literal list.
append_page_body( VALUE )
This method allows you to append content to the current "page body". The argument VALUE can be either an array ref or scalar or literal list.
prepend_page_body( VALUE )
This method allows you to prepend content to the current "page body". The argument VALUE can be either an array ref or scalar or literal list.
page_search_and_replace( DO_THIS )
This method performs a customizable search-and-replace of this object's "page *" properties. The argument DO_THIS is a hash ref whose keys are tokens to look for and the corresponding values are what to replace the tokens with. Tokens can be any Perl 5 regular expression and they are applied using "s/[find]/[replace]/g". Perl will automatically throw an exception if your regular expressions don't compile, so you should check them for validity before use. If DO_THIS is not a valid hash ref then this method returns without changing anything. Currently, this method only affects the "page body" property, which is the most common activity, but in subsequent releases it may process more properties.
page_as_string()
This method assembles the various "page *" properties of this object into a complete HTML page and returns it as a string. That is, it returns the cumulative string representation of those properties. This consists of a prologue tag, a pair of "html" tags, and everything in between. This method requires HTML::EasyTags to do the actual page assembly, and so the results are consistant with its abilities.
AUTHOR
Copyright (c) 1999-2001, Darren R. Duncan. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. However, I do request that this copyright information remain attached to the file. If you modify this module and redistribute a changed version then please attach a note listing the modifications.
I am always interested in knowing how my work helps others, so if you put this module to use in any of your own code then please send me the URL. Also, if you make modifications to the module because it doesn't work the way you need, please send me a copy so that I can roll desirable changes into the main release.
Address comments, suggestions, and bug reports to perl@DarrenDuncan.net.
SEE ALSO
perl(1), CGI::Portable, HTML::EasyTags.