---
name: "CGI::Formalware"
section: "3pm"
platform: "linux"
package: "libcgi-formalware-perl"
version: "1.16-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/CGI::Formalware"
---

# CGI::Formalware(3pm)

Convert an XML file into a suite of CGI forms.

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

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