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 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

    *   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.

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 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 *<ron@savage.net.au>* in
    1999.

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

LICENCE
    Australian copyright (c) 1999 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