NAME

CGI::Handy - Provides assorted data manipulation functions.

SYNOPSIS

    use CGI::Handy;

    # Assumes $cgi is a CGI object...
    print "<a href=" . updateQuery($cgi,"size","2") . ">Larger</a>" .
        "<a href=" . updateQuery($cgi,"size","1") . ">Smaller</a>";

    # Assumes $template is an HTML::Template object...
    $template->param("list" => escapeAllHtml($listData));

    $cgiList = cgi2list($cgi);
    $cgiHash = cgi2hash($cgi);
    $cookieHash = cgi2cookieHash($cgi);

REQUIRES

Perl5.005

EXPORTS

Default: updateQuery, escapeAllHTML

Optional: cgi2list, cgi2hash, cgi2cookieHash

DESCRIPTION

This is collection of auxiliary CGI/HTML-related functions.

FUNCTIONS

Quick Index: escapeAllHTML, updateQuery

updateQuery

updateQuery(cgi, { name, value }... )

Updates the query portion of a url, replacing, adding, or deleting the specified parameter(s). Any number of name-value pairs may be given. Writing this URL into an HTML page as a hyperlink will provide the user with a link to call the same page with different parameter values. Note that the original cgi object is not modified. That is, you may add a parameter to generate one URL variation with one function call, then add a different parameter with a second function call, and in each case you will have modified the original URL.

Note that the URL is generated with the booleans absolute and query passed to the CGI object's url method.

Parameters:: cgi - CGI object; name - string; name of parameter; value - string; value of parameter; if undef, then the parameter <name> is deleted from the URL.
Returns:: Query to call the same URL with the single parameter updated to the new value.

escapeAllHTML

escapeAllHTML(anything)

This is a handy utility for generating valid HTML with HTML::Template objects. Valid HTML requires, for example, that a literal ampersand be given as an entity (&). The standard CGI module has just such a method to do this, escapeHTML. That method operates strictly on strings.

When using the HTML::Template module, however, one typically passes a structure that may be an arbitrarily nested hash reference. This escapeAllHTML method, then, simply applies the standard escapeHTML method to all strings contained within the argument(s).

Parameters:: anything - string or array or hash or reference
Returns:: Passed-in object(s) with HTML entities escaped.

BUGS

updateQuery (like the CGI module itself) does not keep track of the fragment identifier (#xxx) of a url.

AUTHOR

Michael Sorens

VERSION

$Revision: 8 $ $Date: 2006-12-19 21:13:43 -0800 (Tue, 19 Dec 2006) $

SINCE

CleanCode 0.9