NAME
`CGI::Formalware' - 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' 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.
INSTALLATION
You install `CGI::Formalware', as you would install any perl
module library, by running these commands:
perl Makefile.PL
make
make test
make install
If you want to install a private copy of `CGI::Formalware' in
your home directory, then you should try to produce the initial
Makefile with something like this command:
perl Makefile.PL LIB=~/perl
or
perl Makefile.PL LIB=C:/Perl/Site/Lib
If, like me, you don't have permission to write man pages into
unix system directories, use:
make pure_install
instead of make install. This option is secreted in the middle
of p 414 of the second edition of the dromedary book.
AUDIENCE
Webmasters.
SECURITY
None. Even worse, `CGI::Formalware' 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.
Herewith a sample:
H1
{
font-size: 20pt;
alignment: center;
color: teal;
}
H2
{
font-size: 16pt;
font-style: italic;
color: maroon;
}
P.TOC
{
font-size: 12pt;
color: white;
background-color: blue;
}
ENVIRONMENT VARIABLES
None.
INPUT DATA VALIDATION
These checks are performed:
* Each forms entity may have a 'tocEntry' attribute. If present,
and if the tocVisible attribute is 'true', then a Table of
Contents is put on each form, headed by this text. The
default is 'Contents'
* Each forms entity may have a 'tocVisible' attribute. If its
value is 'True', then a Table of Contents is put on each
form, headed by the value of 'tocEntry'. The default is
'True'
* Each form entity must have 'heading' and 'tocEntry' attributes
* Each form entity must have a unique 'heading' attribute
* Each form entity may have a unique 'formFileName' attribute. If
present, then this file name is used to output the form to a
file if the constructor option new({'form2file' => 1}) is
used
* Each textField entity must have 'name', 'prompt', and 'value'
attributes
* Each textField entity must have 'name', 'prompt', 'value' and
'size' attributes
* Each scripts entity must have a 'heading' attribute
* Each script entity must have 'heading', 'type' and 'line'
attributes
* Each script entity must have a unique 'heading' attribute
* Each script entity's 'type' attribute must be 'local' or
'remote'
XML DTD
TBA.
XML FILE FORMAT
Herewith a sample:
<forms
tocEntry = 'Forms'
tocVisible = 'True'
>
<form
heading = 'Unix Command Menu'
tocEntry = 'Unix menu'
css = '/CGI-Formalware.css'
formFileName = '1.html'
>
<horizontalRule/>
<radioGroup
name = 'host'
prompt = 'Host: '
value = 'bigBox|littleBox'
/>
<paragraph/>
<textField
name = 'username'
prompt = 'Username: '
value = ''
size = '15'
override = '0'
/>
<textField
name = 'password'
prompt = ' Password: '
value = ''
size = '15'
override = '0'
/>
<horizontalRule/>
<scripts
heading = 'Unix Scripts'
numberScripts = 'Yes'
>
<script
heading = 'Files in home directory'
type = 'remote'
line1 = 'dir'
/>
<script
heading = 'Tags in repository'
type = 'remote'
line1 = 'cd $M'
line2 = 'getTags'
/>
</scripts>
</form>
<form
heading = 'DOS Command Menu'
tocEntry = 'DOS menu'
>
<horizontalRule/>
<radioGroup
name = 'host'
prompt = 'Host: '
value = 'bigBox|littleBox'
/>
<paragraph/>
<textField
name = 'username'
prompt = 'Username: '
value = ''
size = '15'
override = '0'
/>
<textField
name = 'password'
prompt = ' Password: '
value = ''
size = '15'
override = '0'
/>
<horizontalRule/>
<textField
name = 'fileName'
prompt = 'Filename: '
value = ''
size = '60'
override = '0'
/>
<horizontalRule/>
<scripts
heading = 'PC Scripts'
>
<script
heading = 'Files in root directory'
type = 'local'
line1 = 'cd \'
line2 = 'dir'
/>
<script
heading = 'FTP something somewhere'
type = 'local'
line1 = 'ftp -n -v'
/>
<script
heading = 'Untar a file'
type = 'local'
line1 = 'cd \'
line2 = 'tar mxvzf %fileName%'
/>
</scripts>
</form>
</forms>
NESTED FORMS
Nope, I don't recognize them. Maybe one day...
REQUIRED MODULES
* CGI
* Net::Telnet
* XML::DOM
TO DO
DOS directory text '... <DIR>' is changed to '... {DIR}', so
that it does not look like HTML. This needs to be handled more
cleanly.
AUTHOR
`CGI::Formalware' was written by Ron Savage
*<ron@savage.net.au>* in 1999.
Copyright (c) 1999 Ron Savage.
Available from http://savage.net.au/Perl.html.
LICENCE
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.