NAME

CGI::Snapp::Demo::Four - A template-free demo of CGI::Snapp using Log::Handler::Plugin::DBI

Synopsis

After installing the module (see "Installation"), do one or both of:

o Use the CGI script

Unpack the distro and copy http/cgi-bin/cgi.snapp.four.cgi to your web server's cgi-bin/ directory, and make it executable.

Then browse to http://127.0.0.1/cgi-bin/cgi.snapp.four.cgi.

o Use the PSGI script

Note: In order to not require users to install Starman or Plack, they have been commented out in Build.PL and Makefile.PL.

Edit httpd/cgi-bin/cgi.snapp.four.psgi and change my value for the web server's doc root from /dev/shm/html to match your set up.

/dev/shm/ is a directory provided by Debian which is actually a RAM disk, and within that my doc root is the sub-directory /dev/shm/html/.

Then, install Plack and Starman and then do one or both of:

o Use Starman

Start starman with: starman -l 127.0.0.1:5174 --workers 1 httpd/cgi-bin/cgi.snapp.four.psgi &

o Use Plack

Start plackup with: plackup -l 127.0.0.1:5174 httpd/cgi-bin/cgi.snapp.four.psgi &

Then, with either starman or plackup, direct your browser to hit 127.0.0.1:5174/.

These commands are copied from comments within httpd/cgi-bin/cgi.snapp.four.psgi. The value 5174 is of course just a suggestion. All demos in this series use port 5171 and up.

Description

This is a version of CGI::Snapp::Demo::Two which shows how to use a plugin such as Log::Handler::Plugin::DBI within a CGI script based on CGI::Snapp.

The output reports which methods were and were not entered per run mode.

Using a plugin easily requires a wrapper class, which here is CGI::Snapp::Demo::Four::Wrapper. That's why httpd/cgi-bin/cgi.snapp.demo.four.cgi uses the wrapper instead of using this module directly.

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.

Installation

Installing the module

Install CGI::Snapp::Demo::Four as you would for any Perl module:

Run:

cpanm CGI::Snapp::Demo::Four

or run:

sudo cpan CGI::Snapp::Demo::Four

or unpack the distro, and then either:

perl Build.PL
./Build
./Build test
sudo ./Build install

or:

perl Makefile.PL
make (or dmake or nmake)
make test
make install

Configuring the CGI script's source code and the logger's config file

You must edit both the source code of httpd/cgi-bin/cgi.snapp.demo.four.cgi and the config (text) file, to make this demo work.

Details:

o The CGI script's source code

In cgi.snapp.demo.four.cgi you'll see this code (which is my default set up, /dev/shm/ being Debian's RAM disk):

my($doc_root)    = $ENV{DOC_ROOT} || '/dev/shm';
my($config_dir)  = "$doc_root/assets/config/cgi/snapp/demo/four";
my($config_file) = "$config_dir/config.logger.conf";

Adjust those 3 lines to suit your environment.

Then copy cgi.snapp.demo.four.cgi to your web server's cgi-bin/ directory, and make it executable.

o The logger's config file

This module ships with t/config.logger.conf, which is a copy of the same file from Log::Handler::Plugin::DBI.

So, copy the file t/config.logger.conf to $config_file, as above, and edit it as desired.

Log::Handler::Plugin::DBI ships with a program, scripts/create.table.pl, which can be used to create the 'log' table, using this very config file.

That module's FAQ describes the expected structure of the 'log' table.

With everything in place, and having run the CGI script from the command line (as recommended in "Troubleshooting"), continue with the procedure suggested in the "Synopsis".

Constructor and Initialization

new() is called as my($app) = CGI::Snapp::Demo::Four -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type CGI::Snapp::Demo::Four.

See http/cgi-bin/cgi.snapp.four.cgi.

Methods

run()

Runs the code which responds to HTTP requests.

See http/cgi-bin/cgi.snapp.four.cgi.

Troubleshooting

It doesn't work!

Hmmm. Things to consider:

o Run the *.cgi script from the command line

shell> perl httpd/cgi-bin/cgi.snapp.four.cgi

If that doesn't work, you're in b-i-g trouble. Keep reading for suggestions as to what to do next.

o Check your edits to Four.pm and config.logger.conf

Most likely the edits are wrong, or the files are installed in the wrong directories, or the file permissions are wrong.

o The system Perl 'v' perlbrew

Are you using perlbrew? If so, recall that your web server will use the first line of http/cgi-bin/cgi.snapp.four.cgi to find a Perl, and that line says #!/usr/bin/env perl.

So, you'd better turn perlbrew off and install this module under the system Perl, before trying again.

o Generic advice

http://www.perlmonks.org/?node_id=380424.

See Also

CGI::Application

The following are all part of this set of distros:

CGI::Snapp - A almost back-compat fork of CGI::Application

CGI::Snapp::Demo::One - A template-free demo of CGI::Snapp using just 1 run mode

CGI::Snapp::Demo::Two - A template-free demo of CGI::Snapp using N run modes

CGI::Snapp::Demo::Three - A template-free demo of CGI::Snapp using the forward() method

CGI::Snapp::Demo::Four - A template-free demo of CGI::Snapp using Log::Handler::Plugin::DBI

CGI::Snapp::Demo::Four::Wrapper - A wrapper around CGI::Snapp::Demo::Four, to simplify using Log::Handler::Plugin::DBI

Config::Plugin::Tiny - A plugin which uses Config::Tiny

Config::Plugin::TinyManifold - A plugin which uses Config::Tiny with 1 of N sections

Data::Session - Persistent session data management

Log::Handler::Plugin::DBI - A plugin for Log::Handler using Log::Hander::Output::DBI

Log::Handler::Plugin::DBI::CreateTable - A helper for Log::Hander::Output::DBI to create your 'log' table

Machine-Readable Change Log

The file CHANGES was converted into Changelog.ini by Module::Metadata::Changes.

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=CGI::Snapp::Demo::Four.

Author

CGI::Snapp::Demo::Four was written by Ron Savage <ron@savage.net.au> in 2012.

Home page: http://savage.net.au/index.html.

Copyright

Australian copyright (c) 2012, Ron Savage.

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Artistic License, a copy of which is available at:
http://www.opensource.org/licenses/index.html

cpanm CGI::Snapp::Demo::Four

perl -MCPAN -e shell
install CGI::Snapp::Demo::Four