Subject: ANNOUNCE: CGI::Formalware
From: "Pen and Ron Savage" <[email-masked]>
Date: 31 Mar 1999 13:24:51 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.modules

The Perl module CGI::Formalware is now available from CPAN
and from my web site http://www.ozemail.com.au/~rpsavage.

Documentation is in the module, in POD format, and can be
extracted with
 Prompt>pod2html -infile=Formalware.pm -outfile=Formalware.html

Some parts of the POD follow...

NAME
----
CGI::Formalware.pm - Convert an XML file into a suite of CGI forms.

SYNOPSIS
--------
In your browser, type: localhost/cgi-bin/x.pl

where x.pl contains nothing more than:

 #!perl -w
 use integer;
 use strict;
 use lib 'C:/Perl';
 use lib 'C:/Perl/Scripts/General'; # Ie $PERL5LIB.
 use CGI::Formalware;
 my($form) = CGI::Formalware -> new({'form2file' => 1, 'debug' => 1});
 $form -> process();
 exit(0);

Upon starting, CGI::Formalware.pm asks for the name of your XML file, which
is assumed to be in cgi-bin/.

DESCRIPTION
-----------
To provide a type of repository for frequently used scripts, which can then
be executed
locally or remotely (via Net::Telnet), by just entering a password (for
remote scripts),
and clicking.

AUDIENCE
--------
Webmasters.

SECURITY
--------
None. Even worse, CGI::Formalware.pm is designed to circumvent a web
server's
concept of what Apache calls DocumentRoot.

CONSTRUCTOR new
---------------
new takes either no parameters, or an anonymous hash. See the example above.
Keys and values recognized are:

'debug' => '1' means turn on debugging. At the moment this opens and closes
the
file CGI-Formalware.log, but does not write anything to it

'form2file' => '1' means output each form to a file, using the name given
by the form's formFileName attribute. The forms are written to cgi-bin/.
If the form has no such attribute, this option is ignored. See example below

'timeScripts' => '1' means report elapsed time at the end of each script's
output

HIGHLIGHTS
----------
Read an XML file, whose format is fixed, and generate a suite of CGI forms

A cascading style sheet can be specified for each form individually

A Table of Contents may appear on each form

Each form is more-or-less assumed to contain a list of scripts

Entities in the XML correspond to a few functions available in Lincoln
Stein's
CGI.pm. Eg: textField, radioGroup, horizontalRule. Over time, more functions
will
be added

A textField with the name 'password' is treated as a password field. Also,
the entity 'script' defines a Unix- or DOS-type batch file

These entities produce on-screen fields, or, in the case of the scripts, a
vertical array of radio buttons

So, to run a script you fill in whatever fields the script uses and then
select
that script

Macros in the scripts, eg %fileName% are expanded with the current value of
the
field whose name appears between the % signs

A script whose last line is 'ftp -n -v' is recognized and handled specially.
Your form must contain textFields called 'host', 'username' and 'password'
and
'fileName'. A binary 'get' is performed. This will be made more flexible one
day

Scripts have an attribute 'type', which can be 'local' or 'remote'.

Remote scripts are passed to Net::Telnet, on the assumption that you know
what
you are doing. Your form must contain textFields called 'host', 'username'
and
'password'

NAVIGATION
----------
Forms are linked with 'Previous form', 'Next form' buttons.

Any previously-entered textFields, except those whose name is 'password',
are
remembered when you return to a form. This is very convenient.

The password values are zapped by CGI.pm, not by me. This is a security
feature.
It means you can walk away from your system and not have someone gain
automatic
access to a remote system.

CASCADING STYLE SHEETS
----------------------
Each form entity may have a 'css' attribute, giving the name of the CSS file
for
that form. These attribute values are like '/CGI-Formalware.css', which,
under
Apache, means this value is prefixed with DocumentRoot. That is, the path to
the
CSS is a URI, and will not be seen if in cgi-bin/.

The compulsory elements are: H1, H2 and P.TOC.

See the POD for details.

XML FILE FORMAT
---------------
See the POD for details.

REQUIRED MODULES
----------------
CGI
Net::Telnet
XML::DOM

--
Cheers
Pen and Ron Savage
[email-masked]
http://www.ozemail.com.au/~rpsavage