view release on metacpan or  search on metacpan

lib/CGI/Session/MembersArea.pm  view on Meta::CPAN

=head1 NAME

C<CGI::Session::MembersArea> - A resource guardian based on CGI::Session

=head1 Synopsis

This module does not have to be used in a module derived from CGI::Application, but this
synopsis assumes that that is in fact what you are trying to do.

	use CGI::Application;
	use CGI::Session::MembersArea;
	use DBIx::Admin::DatabaseModel;

	our @ISA = qw/CGI::Application/;

	sub setup
	{
	  my($self) = @_;
	  ...
	  $self -> param(database => '');
	  $self -> param(guardian => '');
	  $self -> param(profile => '');
	  $self -> mode_param(\&setup_mode);

	}	# End of setup.

	sub setup_mode
	{
	  ...
	  $self -> param(guardian => CGI::Session::MembersArea -> new
	  (
	    username  => 'root',
	    password  => 'pass',
	    query     => $self -> query(),
	  ) );

	  $self -> param(profile => $self -> param('guardian') -> init() );

	  if ($self -> param('profile') )
	  {
	    $self -> param
	    (
	      database => DBIx::Admin::DatabaseModel -> new
	      (
	        dsn      => $self -> param('my_dsn'),
	        username => $$profile{'username'},
	        password => $$profile{'password'},
	      )
	    );

	    $self -> param('database') -> param(profile => $self -> param('profile') );
	  }

	}	# End of sub setup_mode.

=head1 Description

C<CGI::Session::MembersArea> is a pure Perl module.

It implements an idea from the CGI::Session CookBook, in the section called Member's Area.

It uses a database as a guardian to control access to resources. These resources are
usually other databases, but don't have to be.

When a user supplies their name and password via a CGI form, this module uses 3 items:

=over 4

=item Resource name

=item User name

=item Password

=back

to determine whether or not that user is allowed access to the resource.

If you don't want the user to have to input a resource name, just change the CGI object
like this, to force the resource to always have the same name:

	$q -> param(my_resource => 'Some value');

This module uses these 3 items when it searches a database table, called 'user' by
default.

If that user is found in the database, the user's profile is returned by C<sub init()>.
The profile is defined below.

It is assumed the program using this module will also use CGI::Session, in which case
the program can save the profile to some database via the CGI::Session object, as in the
synopsis.

See the section of this document called Resources (as it happens), which contains the URI
of a database administration package (myadmin.cgi) which uses this module.

The guardian database contains a single table called, by default, 'user'. This table is
assumed to be in a database called, by default, 'myadmin'. Of course, the table could even
be in one of the databases being protected.

Because there are, normally, 2 or more databases involved, great care must be taken to
ensure you are clear in your mind as to which database is being referred to by any
particular piece of code.

When I refer to the database called 'myadmin', I will always call it the guardian database.

Here is the structure of the 'user' table:

=over 4

=item user_id

Not used. Typically an auto-incrementing row number.

=item user_full_name

The name of the user who might be permitted access to the resource, typically entered by
the user in a CGI form.

The value entered by the user of the CGI script is extracted from the query object.