CGI::Formalware(3pm)

📦
version 1.16 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

🎀 CGI::Formalware(3pm) 🎀

okay so bestie, this is the CGI::Formalware(3pm) page from the User Contributed Perl Documentation situation, and it's literally about turning XML into CGI forms. no cap. 💖

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

The whole vibe is 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. iconic.

💅 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. periodt.

💀 SECURITY 💀

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

not me exposing the whole DocumentRoot situation 😭 stay safe bestie.

🛠️ 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'

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 ✨

okay bestie, here’s a sample, literally the whole XML vibe — no cap:

<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. The legal bit, bestie:

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

That’s the whole page, babe! This is CGI::Formalware(3pm), from perl v5.36.0, dated 2022-10-14. Slay, you made it to the end. 💖✨🦋

📦 where this page comes from