cs::CGI - a replacement for the more common CGI module
use cs::CGI;
The cs::CGI module is a replacement for the CGI module normally obtained from CPAN. Originally written as a wrapper to work around its extremely annoying ``propagate query parameters to new form elements'' ``feature'', it is now a mostly complete replacement with a very different approach to creating new forms.
Shorthand call to the cs::HTML::tok2s function, to turn an HTML token structure into a text stream.
Shorthand call to the cs::HTTP::hexify function, to replace special characters in string with %xx escapes.
Return string with all %xx escapes converted into characters.
This creates a new cs::CGI object from the query parameters in source, the environment variables in env, and with default output (for the Print method) of sink.
Any of these may be omitted or undef, defaulting to: STDIN for source, %ENV for environment and STDOUT for sink.
Return the value named key from the environment. If key is omitted, return the environment hashref itself in a scalar context or the list of key values in an array context.
Query()
Return the query parameter hashref.
Values()
Return the query parameter hashref in a scalar context or the list of parameter names in an array context (for use with Value, below).
Return the value of the parameter named key or default if the parameter was not present. Returns the textual value of the parameter in a scalar context. In an array context the value is split on whitespace into a list of words. If the parameter is not present and default is omitted, returns undef or () depending on context.
Method()
Return the HTTP method used to call this CGI (GET or POST).
Keywords()
Return the parameter names from the query.
Query_String()
Return the QUERY_STRING environment value, unhexified.
ScriptURL()
Return the URL of the script with respect to the server root from the SCRIPT_NAME environment value.
Return the full URL of the CGI invocation: with the PathInfo appended but without the ?Query_String. The optional parameter usehost specifies that the leading http://hostpart is to be supplied; default is false.
Returns the full URL needed to repeat this query via a GET method. The optional parameter usehost specifies that the leading http://hostpart is to be supplied; default is false.
Returns the full URL needed to call this CGI with an arbitrary query via a GET method. Omits the ``?query_string'' if the query-hashref is omitted. The optional parameter usehost specifies that the leading http://hostpart is to be supplied; default is false.
PathInfo($)
Returns the PATH_INFO environment value (the URL path components past the CGI script itself). Returns a string in a scalar context or the components split on slashes in an array context.
Return a new cs::HTML::Form object for the specified action and method. If omitted, action defaults to ScriptURL and method defaults to GET.
This cs::HTML::Form object can then be used to construct form markup, and added to the CGI's markup token list as usual via the cs::HTML::Form::Close method:
... do form construction here ...
push(@html, $F->Close());
This method takes:
an URL to call a CGI script, such as SelfQuery()
a hashref pointing at a table of fields and data types
a hashref pointing at a record with fields matching the schema
a hashref containing arbirary state information to be passed through the form as a hidden field (this parameter may be omitted)
and returns an HTML token list for a form to edit the fields named in the schema. Quick and dirty, not pretty.
The action CGI script can the used the GetEdits method below to extract the altered fields in the form for use. (The original record contents are passed through as hidden parameters for comparison).
The purpose to returning only the changed fields is to previde a degree of robustness against parallel editing of a record. Supposing person A loads the record up for editing and then gets delayed. Meanwhile, person B loads up the same record and edits a different field. Later, person A returns and submits his/her edits. Were the whole record rewritten to the backend database B's changes would be lost. This technique keeps both changes provided they don't overlap.
Take a query hashref (by default the query supplied to this CGI) and a describing schema (which may be omitted) and return a 2-tuple containing a hashref with the modified fields and the context hashref supplied in MkForm above. Fields not described in the schema are assumed to be TEXTFIELDs.
Add the header hdr to the CGI scripts return headers in the fashion designated by how. This calls the cs::RFC822::Add method.
Replace a header with the supplied hdr. Calls the cs::RFC822::Add method with how set to REPLACE.
Set the Content-Type header to type (by default text/html) with optional parameters specified in the hashref params.
Set the <tag> field (eg TITLE) of the HEAD section of the output HTML to the token <tag attrs>markup</tag>. The attrs is an optional hashref containing tag attributes. The markups may also be omitted.
Append arbirary HTML markup to the HEAD section of the output HTML.
Set the attributes named by each key to the corresponding value in the <HEAD> tag of the output HTML.
Set the attributes named by each key to the corresponding value in the <BODY> tag of the output HTML.
Set a cookie in the headers named name with value value and the parameters specified by the optional hashref param.
Cookies()
Return the hashref describing the cookies supplied to this CGI script.
Emit the CGI's MIME headers and HTML to the output specified by sink. The HTML is a reference to an array of tokens. The tokens are converted to an array of strings for output if need_tok2a is true (its default value). If omitted, the sink defaults to the sink supplied in the new call (which itself defaults to STDOUT).
Thus, the final act of a CGI script using this module
will be a $CGI->Print(\@html) call.
cs::RFC822(3), cs::HTTP(3), cs::HTML(3), cs::HTML::Form(3).
Cameron Simpson <cs@zip.com.au>