NAME

LibWeb::CGI - Extra cgi supports for libweb applications

SUPPORTED PLATFORMS

BSD, Linux, Solaris and Windows.

REQUIRE

LibWeb::Core

ISA

CGI
LibWeb::Class

SYNOPSIS

  use LibWeb::CGI;
  my $q = new LibWeb::CGI();

  my $parameter = $q->parameter('cgi_param_to_fetch');

  my $param = $q->param('cgi_param_to_fetch');

  print $q->header();

  $q->redirect( -url => '/cgi-bin/logout.cgi', -cookie => 'auth=0' );

  $q->send_cookie( [$cookie1, $cookie2] );

  $q->sanitize( -text => $user_input, -allow => ['_', '-'] );

  $q->fatal(
             -msg => 'Password not entered.',
             -alertMsg => '$user did not enter password!',
             -helpMsg => \('Please hit back and edit.')
           );

ABSTRACT

This class ISA the vanilla CGI.pm to provide some additional features. It is still considered to be experimental but used internally by LibWeb::Session and LibWeb::Admin.

The current version of LibWeb::CGI is available at

   http://libweb.sourceforge.net

Several LibWeb applications (LEAPs) have be written, released and are available at

   http://leaps.sourceforge.net

TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY

Variables in all-caps (e.g. MAX_LOGIN_ATTEMPT_ALLOWED) are those variables set through LibWeb's rc file. Please read LibWeb::Core for more information. `Sanitize' means escaping any illegal character possibly entered by user in a HTML form. This will make Perl's taint mode happy and more importantly make your site more secure. Definition for illegal characters is given in LibWeb::Core. All `error/help messages' mentioned can be found at LibWeb::HTML::Error and they can be customized by ISA (making a sub-class of) LibWeb::HTML::Default. Please see LibWeb::HTML::Default for details. Method's parameters in square brackets means optional.

DESCRIPTION

METHODS

new()

args: [ -post_max=>, -disable_uploads=>, -auto_escape=> ]

-post_max is the ceiling on the size of POSTings, in bytes. The default for LibWeb::CGI is 100 Kilobytes.
-disable_uploads, if non-zero, will disable file uploads completely which is the default for LibWeb::CGI.
-auto_escape determines whether the text and labels that you provide for form elements are escaped according to HTML rules. Non-zero value will enable auto escape, and undef will disable auto escape (default for LibWeb::CGI).

header()

If you provide parameter to that method, it will delegate to the vanilla CGI's header(); otherwise, it will print out "Content-Type: text/html$CRLF$CRLF" immediately (faster?). $CRLF will depend on the machine you are running LibWeb and LibWeb will determine it automatically.

parameter()

  my $param = $q->parameter('cgi_parameter_to_fetch');

`cgi_parameter_to_fetch' is the parameter passed by either `GET' or `POST' via a HTML form.
If `cgi_parameter_to_fetch' is a mandatory form value (one without `.' as prefix in the parameter's name) and it is null, it will print out an error message, abort the program and send the site administrator an alert e-mail. It is intended so save the effort to check whether the user has entered something for mandatory HTML form values. To use this nice feature, you name mandatory form value without `.' as prefix, for example,
```
  <input type="text" name="email">
```
For non-mandatory form values, you name them by attaching `.' as a prefix to skip the test, for example,
```
  <input type="text" name=".salary_range">
```
If you find this not really helpful, you should use the vanilla param() which is totally unaltered in LibWeb::CGI. For example,
```
  my $param = $q->param('param_to_fetch');
```
and LibWeb::CGI will delegate the call to the vanilla CGI's param(). Another reason to use parameter() (or not to use it) is that it automatically checks for any possible denial of service attack by calling CGI::cgi_error(). If the POST is too large, it will print out an error message and send an e-mail alerting the site administrator. CGI::cgi_error() is available since CGI 2.47 but seems to be disappeared in new release of CGI.pm 3.01 alpha (24/04/2000).

redirect()

Params:

  -url=> [, -cookie=> ]

This will redirect the client web browser to the specified url and send it the cookie specified. An example of a cookie to pass to that method will be,

  $cookie1 = 'auth1=0; path=/; expires=Thu, 01-Jan-1970 00:00:01 GMT';
  $cookie2 = 'auth2=0; path=/; expires=Thu, 01-Jan-1970 00:00:01 GMT';

  $q->redirect(
               -url => '/logged_out.htm',
               -cookie => [ $cookie1, $cookie2 ]
              );

For -cookie, you can pass either a scalar or an ARRAY reference. This method will eventually delegate to the vanilla CGI's redirect(). Why bother doing this is because the vanilla CGI's redirect() does not guarantee to work if you pass relative url; whereas LibWeb::CGI::redirect() guarantees that partial url will still work.

send_cookie()

This delegates to LibWeb::Core::send_cookie(). See LibWeb::Core.

fatal()

This delegates to LibWeb::Core::fatal(). See LibWeb::Core.

sanitize()

This delegates to LibWeb::Core::sanitize(). See LibWeb::Core.

AUTHORS

Colin Kong (colin.kong@toronto.edu)

CREDITS

Lincoln Stein (lstein@cshl.org)

BUGS

Bug number 1

When you delegate subroutine calls within a cgi script, $q->param(_variable_) or $q->parameter(_variable_) may not give you the value of _variable_ even you have passed a value for that variable in a HTML form. I do not know why. My two workarounds,

Instantiate another CGI or LibWeb::CGI object within the subroutine where you want to fetch the parameter and use that object to call param() or parameter(), or
Initiate all CGI variables and/or fetch all CGI parameters at the beginning of your script.

Bug number 2