CGIS - Session enabled CGI.pm

CGIS documentation Contained in the CGIS distribution.

Index

Code Index:

NAME

Top

CGIS - Session enabled CGI.pm

SYNOPSIS

Top

    use CGIS;

    $cgi = new CGIS;
    my $first_name = $cgi->session("f_name");

    # use it the way you have been using CGI.pm

DESCRIPTION

Top

CGIS is a simple, session-enabled extension for Lincoln Stein's CGI. Instead of loading CGI, you load CGIS, and use it the way you have been using CGI.pm, without any exceptions.

In addition, CGIS provides session() method, to support persistent session management accross subsequent HTTP requests, and partially overrides header() method to ensure proper HTTP headers are sent out with valid session cookies.

CGIS also modifies your CGI environement by appending 'CGISESSID' parameter with session id as a value. It means, self_url() method (CGI) will print URL with session related data intact.

CGIS requires CGI::Session installed properly. Uses its CGI::Session::File driver, and stores session data in a designated directory created in your system's temporary folder.

METHODS

Top

EXAMPLES

Top

A tiny example of a cgi program can be found in examples/ folder of the distribution. You may as well be able to see it in action at http://www.handalak.com/cgi-bin/cgis This script simply displays your session id as well as sample outputs of urlf() and self_url() methods for you to have an idea.

In session management enabled sites, you most likely send proper session cookie to the user's browser at each request. Instead of doing it manual, simply call CGIS's header() method, as you would that of CGI.pm's:

    print $cgi->header();

And you are guaranteed proper cookie's sent out to the user's computer.

STORING DATA IN THE SESSION

    # store user's name in the session for later use:
    $cgi->session("full_name", "Sherzod Ruzmetov");

    # store user's email for later:
    $cgi->session("email", 'sherzodr@cpan.org');

READING DATA OFF THE SESSION

    my $full_name = $cgi->session("full_name");
    my $email     = $cgi->session('email');
    print qq~<a href="mailto:$email">$full_name</a>~;

GETTING CGI::Session OBJECT

For performing more sophisticated oprations, you may need to get underlying CGI::Session object directly. To do this, simply call session() with no arguments:

    $session = $cgi->session();    

    # set expiration ticker for session object
    $session->expire("+10m");

For more tricks, consult CGI::Session manual.

AUTHOR

Top

Sherzod B. Ruzmetov <sherzodr@cpan.org>

COPYRIGHT

Top

This library is free software. You can modify and/or distribute it under the same terms as Perl itself.

SEE ALSO

Top

CGI::Session, CGI

CGIS documentation Contained in the CGIS distribution. 
package CGIS;

# $Id: CGIS.pm,v 1.6 2003/03/12 11:43:34 sherzodr Exp $

use strict;
#use diagnostics;
use base 'CGI';

($CGIS::VERSION) = '$Revision: 1.6 $' =~ m/Revision:\s*(\S+)/;

# Preloaded methods go here.

sub session {
  my $self = shift;
      
  my $session_obj = $self->{_CGI_SESSION_OBJ};
  unless ( defined $session_obj ) {
    require CGI::Session;
    my $session_dir = $self->cgi_session_dir();
    $session_obj = new CGI::Session(undef, $self, {Directory=>$session_dir});
    $self->{_CGI_SESSION_OBJ} = $session_obj;
    $self->param($session_obj->name, $session_obj->id);
  }
  unless ( @_ ) {
    return $session_obj;
  }
  return $session_obj->param(@_);
}


# returns the folder to store session files in
sub cgi_session_dir {
  my $self = shift;

  require File::Spec;
  # getting the temporary directory
  my $tmpdir = File::Spec->tmpdir();
  # directory name to store cgisession data in:
  my $session_dir = File::Spec->catfile($tmpdir, 'cgi_session');
  unless ( -d $session_dir ) {
    require File::Path;
    unless(File::Path::mkpath($session_dir)) {
      # if fails to create the folder, fall back to default tmpdir
      $session_dir = File::Spec->tmpdir();
    }
  }  
  return $session_dir;
}



# alias to cgi_session_dir()
sub session_dir {
  my $self = shift;
  return $self->cgi_session_dir();
}



sub header {
  my $self = shift;

  my $session   = $self->session();
  my $cookie    = $self->cookie($session->name, $session->id);
  return $self->SUPER::header(-cookie=>$cookie, @_);
}



sub urlf {
  my $self = shift;

  my $session = $self->session();
  my $name = $session->name;

  my %args = (
    $name => $session->id,
    @_
  );  

  require URI;
  my $url = new URI( $self->url )->canonical();
  $url->query_form( %args );

  return $url->as_string();
}


sub session_id {
  my $self = shift;

  return $self->session()->id;
}








1;
__END__
# Below is stub documentation for your module. You better edit it!