LibWeb -- a vanilla web site backend current version: 0.02  
Home | Requirements | Features | Documentation | Downloads | License
  Sourceforge
Control panel
CVS
News
Bug Tracking
Mailing lists
Message forums
Downloads

  Sponsors
SourceForge.net
Documentation:

LibWeb::Core

NAME

LibWeb::Core - The core class for libweb modules


SUPPORTED PLATFORMS

BSD, Linux, Solaris and Windows.


REQUIRE

  • LibWeb::Crypt

  • LibWeb::HTML::Error

  • Mail::Sendmail


ISA

  • LibWeb::Class


SYNOPSIS

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


ABSTRACT

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
 


TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY

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.


DESCRIPTION


READING THE LIBWEB RC FILE

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.


SANITY -- REMOVING ILLEGAL CHARACTERS ENTERED BY USERS

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().


METHODS

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.


AUTHORS

Colin Kong (colin.kong(at)utoronto.ca)


CREDITS


BUGS


SEE ALSO

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.



Copyright © 2000-2002 LibWeb.
All trademarks and copyrights on this page are properties of their respective owners. Forum comments are owned by the poster.