LibWeb::Core - The core class for libweb modules

BSD, Linux, Solaris and Windows.

• LibWeb::Crypt
• LibWeb::HTML::Error
• Mail::Sendmail

• LibWeb::Class

  require LibWeb::Core;
  @ISA = qw(LibWeb::Core);

This class is responsible for reading the LibWeb's rc file, handling portability issues, printing and logging error and debug messages and sending alert e-mail to the site administrator should error occur. You are not supposed to use or ISA this class directly. It is ISAed internally by other modules in LibWeb, e.g. LibWeb::Admin, LibWeb::CGI, LibWeb::Database, LibWeb::HTML::Default and LibWeb::Themes::Default. You should call the methods presented in this man page through one of those sub-classes.

The current version of LibWeb::Core is available at

   http://libweb.sourceforge.net

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

   http://leaps.sourceforge.net

Variables in all-caps (e.g. ADMIN_EMAIL) are those variables set through LibWeb's rc file. `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. 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.

You should place your LibWeb rc (config) file outside your WWW document root. The following shows how a cgi script using LibWeb will typically look like,

  use LibWeb::Session;
  use LibWeb::Database;
  use LibWeb::CGI;
  use LibWeb::Themes::Default;
  use LibWeb::HTML::Default;

  my $rc_file = '/home/me/dot_lwrc';

  my $html = new LibWeb::HTML::Default($rc_file);
  my $themes = new LibWeb::Themes::Default();
  my $session = new LibWeb::Session();
  my $db = new LibWeb::Database();
  my $q = new LibWeb::CGI();

  ...

It is recommended that you pass the absolute path of LibWeb's rc file to LibWeb::HTML::Default and make it the *first* LibWeb object initialized. This will ensure other LibWeb objects can ``see'' the rc file and be initialized properly.

However, LibWeb::Admin, LibWeb::CGI, LibWeb::Database, LibWeb::Themes::Default, and LibWeb::Session all can take $rc_file as the argument to their new() methods (constructor). You will never need this unless you do not want LibWeb::HTML::Default to manage HTML page display for you.

You still do *not* need this even if you have ISAed LibWeb::HTML::Default. The reason to ISA LibWeb::HTML::Default is to customize the normal and error HTML page display and error messages built into LibWeb. If you have ISAed LibWeb::HTML::Default, you just have to replace the following two lines,

  use LibWeb::HTML::Default;
  my $html = new LibWeb::HTML::Default($rc_file);

with

  use MyHTML;
  my $html = new MyHTML($rc_file);

where MyHTML is your class which ISAs LibWeb::HTML::Default. Please read LibWeb::HTML::Default for details. A sample rc file has been included in the ./eg directory. If you could not find it, please go to http:://libweb.sourceforge.net and download a standard LibWeb distribution.

LibWeb::Core provides sanitize() method to escape illegal characters entered by users in HTML forms. LibWeb's definition of illegal characters is as follows,

  `~!@#$%^&*,.:;?"'<>{}[]()\|/-_+=\a\n\r\t\f\e\b

sanitize() also has the ability to escape HTML tags and detect dirty e-mail addresses (format). Please see below for details on sanitize().

new()

Params:

class [, rc_file, error_object]

Usage:

  No, you do not call LibWeb::Core::new()
  directly in client codes.

• class is the class/package name of this package, be it a string or a reference.
• rc_file is the absolute path to the rc file for LibWeb.
• error_object is a reference to a perl object for printing out error/help message to users should error occur.

debug_print()

Usage:

  debug_print('you debug message');

• If `DEBUG' == 1, print debug_msg and return undef. Do nothing otherwise.

fatal()

Params:

  -msg [, -input=>, -helpMsg=>, -alertMsg=>,
          -isAlert=>, -isDisplay=>, -cookie=> ]

Usage:

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




  fatal(
         -alertMsg =>
         'Possible denial of service attack detected!',
         -isDisplay => 0
       );

Pre:

• -msg, -input, -alertMsg must be scalar and -helpMsg must be a SCALAR reference. -cookie can be a scalar or an ARRAY reference to scalars,
• -input is the user input that triggers this fatal error,
• -helpMsg is any instruction to guide the remote user, which can be HTML,

Post:

• Send -cookie, print -msg, -input and -helpMsg to the viewing web browser and abort the current running program if -isDisplay is defined and is equal to 1 (default),
• if -isAlert is defined and is equal to 1 (default),
• • append -alertMsg to `FATAL_LOG' if `FATAL_LOG' is defined,
  • send an alert e-mail, with -alertMsg as the message body, to `ADMIN_EMAIL' if `IS_MAIL_DEBUG_TO_ADMIN' is 1, and
  • print -alertMsg to the viewing web browser if `DEBUG' is 1.

sanitize(): sanitizes Web client inputs

Params:

  -text=>'plain_text' || -html=>'html_text' ||
  -email=>'email_here' [, -allow=>[characters allowed] ]

Usage:

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

  @sanitized_emails =
      sanitize( -email => [$email1,$email2, $email3] );

  $sanitized_input =
      sanitize( -html => $user_input );

Pre:

• For -text, -html and -email, each must be a scalar or an ARRAY reference to scalars,
• -allow is an ARRAY reference to special characters allowed. It's effective only when you use it with -text.

Post:

• -text: sanitize text by escaping all illegal characters (`~!@#$%^&*,.:;?"'<>{}[]()\|/-_+=\a\n\r\t\f\e\b),
• -html: escape all html <> tags,
• -email: sanitize email addresses. Print an error message and abort the current running program if email is dirty ( $email !~ m:(\w{1}[\w-.]*)\@([\w-.]+): )
• array is returned if want array,
• this can only process one type of sanity at a time (i.e. per method call).

send_cookie() -- this one is here due to inheritance (backward?) issues not yet resolved with LibWeb::CGI.

Usage:

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

  send_cookie( $cookie1 ); # or

  send_cookie( [$cookie1, $cookie2] );

Pre:

• Parameter must be either a scalar or an ARRAY reference to scalars,
• no other HTTP headers should be sent before this in a single CGI session.

Post:

• Send the cookie to client Web browser.

send_mail()

Params:

  -to=>, -from=>, -subject=>, -msg=>
  [, -replyTo=>, -cc=>, -bcc=>, -smtp=> ]

Pre:

• -msg must be a SCALAR reference and others must be scalars.

Post:

• Send an e-mail to the recipients specified. It will try to use Mail::Sendmail and then the primitive unix sendmail if the former fails.

Colin Kong (colin.kong@toronto.edu)

LibWeb::Admin, LibWeb::Class, LibWeb::Core, LibWeb::CGI, LibWeb::Crypt LibWeb::Database, LibWeb::File, LibWeb::HTML::Error, LibWeb::HTML::Site, LibWeb::HTML::Default, LibWeb::Session, LibWeb::Themes::Default, LibWeb::Time.