.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CGI::Formalware 3pm" .TH CGI::Formalware 3pm "2022-10-14" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "CGI::Formalware" \- Convert an XML file into a suite of CGI forms. .SH "SYNOPSIS" .IX Header "SYNOPSIS" In your browser, type: localhost/cgi\-bin/x.pl .PP where x.pl contains nothing more than: .PP .Vb 8 \& #!perl \-w \& use strict; \& use lib \*(AqC:/Perl\*(Aq; \& use lib \*(AqC:/Perl/Scripts/General\*(Aq; # Ie $PERL5LIB. \& use CGI::Formalware; \& my($form) = CGI::Formalware \-> new({form2file => 1, debug => 1}); \& $form \-> process(); \& exit(0); .Ve .PP Upon starting, \f(CW\*(C`CGI::Formalware\*(C'\fR asks for the name of your \s-1XML\s0 file, which is assumed to be in cgi\-bin/. .SH "DESCRIPTION" .IX Header "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. .SH "INSTALLATION" .IX Header "INSTALLATION" You install \f(CW\*(C`CGI::Formalware\*(C'\fR, as you would install any perl module library, by running these commands: .PP .Vb 4 \& perl Makefile.PL \& make \& make test \& make install .Ve .PP If you want to install a private copy of \f(CW\*(C`CGI::Formalware\*(C'\fR in your home directory, then you should try to produce the initial Makefile with something like this command: .PP .Vb 3 \& perl Makefile.PL LIB=~/perl \& or \& perl Makefile.PL LIB=C:/Perl/Site/Lib .Ve .PP If, like me, you don't have permission to write man pages into unix system directories, use: .PP .Vb 1 \& make pure_install .Ve .PP instead of make install. This option is secreted in the middle of p 414 of the second edition of the dromedary book. .SH "AUDIENCE" .IX Header "AUDIENCE" Webmasters. .SH "SECURITY" .IX Header "SECURITY" None. Even worse, \f(CW\*(C`CGI::Formalware\*(C'\fR is designed to circumvent a web server's concept of what Apache calls DocumentRoot. .SH "CONSTRUCTOR new" .IX Header "CONSTRUCTOR new" new takes either no parameters, or an anonymous hash. See the example above. Keys and values recognized are: .IP "\(bu" 4 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 .IP "\(bu" 4 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 .IP "\(bu" 4 timeScripts => 1 means report elapsed time at the end of each script's output .SH "HIGHLIGHTS" .IX Header "HIGHLIGHTS" .IP "\(bu" 4 Read an \s-1XML\s0 file, whose format is fixed, and generate a suite of \s-1CGI\s0 forms .IP "\(bu" 4 A cascading style sheet can be specified for each form individually .IP "\(bu" 4 A Table of Contents may appear on each form .IP "\(bu" 4 Each form is more-or-less assumed to contain a list of scripts .IP "\(bu" 4 Tokens in the \s-1XML\s0 correspond to a few functions available in Lincoln Stein's \&\s-1CGI\s0.pm. Available tokens are: .RS 4 .IP "\(bu" 4 fileField .Sp .Vb 6 \& .Ve .IP "\(bu" 4 horizontalRule .Sp .Vb 1 \& .Ve .IP "\(bu" 4 paragraph .Sp .Vb 1 \& \& \& .Ve .IP "\(bu" 4 radioGroup .Sp .Vb 6 \& .Ve .IP "\(bu" 4 textField .Sp .Vb 7 \& .Ve .RE .RS 4 .Sp Over time, more functions will be added. .RE .IP "\(bu" 4 A textField with the name 'password' is treated as a password field. Also, the entity 'script' defines a Unix\- or DOS-type batch file .IP "\(bu" 4 These entities produce on-screen fields, or, in the case of the scripts, a vertical array of radio buttons .IP "\(bu" 4 So, to run a script you fill in whatever fields the script uses and then select that script .IP "\(bu" 4 Macros in the scripts, eg \f(CW%fileName\fR% are expanded with the current value of the field whose name appears between the % signs .IP "\(bu" 4 A script whose last line is 'ftp \fB\-n\fR \fB\-v\fR' 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 .IP "\(bu" 4 Scripts have an attribute 'type', which can be 'local' or 'remote'. .Sp 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' .SH "NAVIGATION" .IX Header "NAVIGATION" Forms are linked with 'Previous form', 'Next form' buttons. .PP Any previously-entered textFields, except those whose name is 'password', are remembered when you return to a form. This is very convenient. .PP The password values are zapped by \s-1CGI\s0.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. .SH "CASCADING STYLE SHEETS" .IX Header "CASCADING STYLE SHEETS" Each form entity may have a 'css' attribute, giving the name of the \s-1CSS\s0 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 \&\s-1CSS\s0 is a \s-1URI,\s0 and will not be seen if in cgi\-bin/. .PP The compulsory elements are: H1, H2 and P.TOC. .PP Herewith a sample: .PP .Vb 6 \& 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; \& } .Ve .SH "ENVIRONMENT VARIABLES" .IX Header "ENVIRONMENT VARIABLES" None. .SH "INPUT DATA VALIDATION" .IX Header "INPUT DATA VALIDATION" These checks are performed: .IP "\(bu" 4 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' .IP "\(bu" 4 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' .IP "\(bu" 4 Each form entity must have 'heading' and 'tocEntry' attributes .IP "\(bu" 4 Each form entity must have a unique 'heading' attribute .IP "\(bu" 4 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 .IP "\(bu" 4 Each fileField entity must have 'name', 'prompt', 'value' and 'size' attributes .IP "\(bu" 4 Each textField entity must have 'name', 'prompt', 'value' and 'size' attributes .IP "\(bu" 4 Each scripts entity must have a 'heading' attribute .IP "\(bu" 4 Each script entity must have 'heading', 'type' and 'line' attributes .IP "\(bu" 4 Each script entity must have a unique 'heading' attribute .IP "\(bu" 4 Each script entity's 'type' attribute must be 'local' or 'remote' .SH "XML DTD" .IX Header "XML DTD" \&\s-1TBA.\s0 .SH "XML FILE FORMAT" .IX Header "XML FILE FORMAT" Herewith a sample: .PP .Vb 11 \& \&
\& \& \& \& \& \& \& \& \& \& \& \& \& \&