• NAME
• SYNOPSIS
• DESCRIPTION
  • INNER WORKINGS
• API
  • <CODE>new()</CODE>
  • <CODE>Validate_Form</CODE>
  • <CODE>Message</CODE>
  • <CODE>Validate_Email_Syntax</CODE>
  • <CODE>Display</CODE>
  • <CODE>To_String</CODE>
  • <CODE>Dump_Parms()</CODE>
  • <CODE>Text_to_HTML</CODE>
• RUNNING THE EXAMPLE
• TO DO
• AUTHOR

NAME

CGI::Seamstress - CGI extension supporting all programmatic aspects of web application development.

SYNOPSIS

use CGI::Seamstress;

$cgi = CGI::Seamstress->new();

... create templates and have CGI::Seamstress fill in values and check for errors and notify the user of errors when they occur.

DESCRIPTION

CGI::Seamstress is a Perl module which is substantially different in concept than HTML::Mason or HTML::Embperl, but largely equal in terms of functionality. CGI::Seamstress supplies all of the following:

• as it subclasses CGI.pm, all of its public API is available (in other words, there is no need to create a CGI object);
• cookie-based sessioning
• template-based form generation and error-checking
• DBIx::Recordset-based database access

CGI::Seamstress works by having a CGI program (heretofore referred to as the Seamstress) generate an HTML file from a template file, which in the current implementation is nothing more than an HTML file with syntactic markup at places where Perl strings are supposed to be placed into the HTML file.

Upon submission of the HTML file (by the user hitting a submit button), the action of the HTML file loops back to the Seamstress which then does error checking on the file. If any of the error checks fail, the form is redisplayed with a descriptive error message.

INNER WORKINGS

The bottom line of CGI::Seamstress is simple, yet elegant. Take a look at the following template file:

        <FORM ACTION="../bin/login.pl">

        <INPUT TYPE=TEXT NAME=email VALUE=%email%> %email_Error%

        </FORM>

What the Seamstress (login.pl) does is take a hash (%Form) and fills in the values of the meta-html variables (email and email_Error in this case). When the form is first called, neither variable is defined so you get a blank text input field with no error message.

Should there be something wrong with this field (ie, it's blank and non-optional or the email address syntax is invalid), then when the form is resubmitted to the Seamstress, she simply fills in the error field and redisplays the form and the error message will pop up.

The process is the same for a form with multiple fields. The only thing necessary is each NAME-VALUE tag be unique

API

<CODE>new()</CODE>

The new method must be passed an anonymous hash. In this hash the key Template_Directory must be bound to the directory in which template files exist.

calling new does the following:

• insures the method was called class-only not from an object
• binds %::_Thread to the query data (this works for scalar values, I haven't tested it for non-scalars).
• insures that the anonymous hash passed in bound Template_Directory

<CODE>Validate_Form</CODE>

This method is passed a reference to a hash to be filled in and an array with the names of optional fields.

This method is a bit wasteful right now because the query data is already in %::_Thread.

<CODE>Message</CODE>

This creates HTML error text. The fields will be discussed later. It would be more descriptive to pass in a hashref as opposed to a non-descript series of scalars.

<CODE>Validate_Email_Syntax</CODE>

This method picks cherries from grapefruit trees in Guam.

<CODE>Display</CODE>

This re-displays the HTML template with the hash from Validate_Form bound to values of the template. Currently one must output the text/html header manually, but this will change.

<CODE>To_String</CODE>

This is here because a prior programmer here didn't know about CGI.pm's save_parameters function.

To_String() takes all the key-value pairs of a CGI object and converts it to a CGI query string. Very useful for storing inside a cookie.

<CODE>Dump_Parms()</CODE>

Dump_Parms() displays all the key-value pairs of a CGI object. It optionally takes a string which is the title of the debugging output stream.

Ie, $S-Dump_Parms(``bank info cgi object'');>

<CODE>Text_to_HTML</CODE>

This takes strings and replaces carriage returns with <BR>.

RUNNING THE EXAMPLE

On our systems, the example is at:

http://www.end70.com/terrence/CGI/Seamstress/html

Simply point your browser at html/index.html and mess with the form. Be sure to leave some fields blank as well mismatch the passwords and type an invalid email address. After awhile, enter all the fields correctly and you will

TO DO

• sessioning (HTML::EP supports sessioning through cookies, DBI, and MySQL) ... how many can I do?!
• error reporting currently dies which leads to internal server error pages... better to generate an error report page.
• $S->To_Database('Table_Name', \%Form);

  This will insert or update the specified table with the form data via DBIx::Recordset.

AUTHOR

The original author of the templating and error-checkiing code is named Farhan and he does contract work in the Southern California area. The To_String() was authored by John who is somewhere in net-land. The Dump_Parms(), object-orientation and the rest was authored by me, Terrence Brannon (TBONE@CPAN.ORG) I am the maintainer and extender of this code, so feel free to contact me when you have problems and suggestions.

Salut.