Formalware

	#!perl -w
	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.

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

Tokens in the XML correspond to a few functions available in Lincoln Stein's CGI.pm. Available tokens are:

fileField

	<fileField
		name		= 'fileName'
		prompt		= 'Filename: '
		size		= '60'
		override	= '0'
	/>

horizontalRule
```
	<horizontalRule />
```

paragraph

	<paragraph />

	<paragraph text = 'Output a comment' />

radioGroup

	<radioGroup
		name		= 'serverName'
		prompt		= 'Server name: '
		value		= 'Example|Simple|Test'
		columns		= '1'	# Optional. Defaults to '1'. Use a string, not a digit
	/>

textField

	<textField
		name		= 'username'
		prompt		= 'Username: '
		value		= ''
		size		= '15'
		override	= '0'
	/>

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.

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 fileField entity must have 'name', 'prompt', 'value' and 'size' 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 text = 'Enter a username and a password.' />

		<textField
			name		= 'username'
			prompt		= 'Username: '
			value		= ''
			size		= '15'
			override	= '0'
		/>

		<textField
			name		= 'password'
			prompt		= '  Password: '
			value		= ''
			size		= '15'
			override	= '0'
		/>

		<horizontalRule />

		<fileField
			name		= 'fileName'
			prompt		= 'Filename: '
			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

AUTHOR

CGI::Formalware was written by Ron Savage in 1999.

Available from http://savage.net.au/Perl.html.

LICENCE

	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

Top of page

Formalware

Table of Contents

Formalware