.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" 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 "CGIEMAIL 1" .TH CGIEMAIL 1 "2016-11-21" "cgiemail v1.6" "cgiemail CGI suite" .\" 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" cgiemail, cgiecho, cgifile \- CGI Form\-to\-Mail conversion tools .SH "The cgiemail user guide" .IX Header "The cgiemail user guide" This guide will help you write a \s-1WWW\s0 form that sends an e\-mail message to you. The following steps are required: .IP "\(bu" 4 Create an e\-mail template. .IP "\(bu" 4 Put a link to the template on your page. .IP "\(bu" 4 Decide if a mailto: link will do. .IP "\(bu" 4 Create the \s-1HTML\s0 form. .IP "\(bu" 4 Create more advanced \s-1HTML\s0 forms. .IP "\(bu" 4 Make sure the \s-1ACTION\s0 is correct. .IP "\(bu" 4 Try out your form with cgiecho. .IP "\(bu" 4 Go live with cgiemail. .IP "\(bu" 4 Debug if you don't get mail .PP The following steps are optional. .IP "\(bu" 4 Add text to the success page. .IP "\(bu" 4 Use an alternate success page. .IP "\(bu" 4 Make some inputs required. .IP "\(bu" 4 Specify formatting for some inputs. .IP "\(bu" 4 Use \s-1CGI\s0 environment variables. .SS "Create an e\-mail template." .IX Subsection "Create an e-mail template." Before you start receiving e\-mail messages through the web, you should decide what these messages should look like. Create an \s-1ASCII\s0 file, called an e\-mail template, that looks something like this: .PP .Vb 6 \& To: strangeman@chasm.big HEADER LINES \& Subject: questions three \& blank line \& What is your name? [yourname] \& What is your quest? [quest] BODY \& What is your favourite colour? [colour] .Ve .PP In one sense, this template is free-form. People who want to send you e\-mail can download this template, fill it out, and mail it to you. However, the template will also be used by the cgiemail program, so before you upload the file to your \s-1WWW\s0 server, be careful to follow these guidelines: .IP "\(bu" 4 Wherever you want the user of your form to supply information, use a single word inside square brackets with no spaces, e.g. Your name: [yourname]. Not [Put your name here]. .IP "\(bu" 4 Make sure the address in the To: field is correct. .IP "\(bu" 4 If there are blank lines among the header lines, remove them. .IP "\(bu" 4 If there are blank lines before the header lines, remove them. .IP "\(bu" 4 Make sure all your header lines are valid. The first character on the line must be a letter. Most information should go in the message body; don't make up your own headers. .IP "\(bu" 4 Make sure there is a blank line between the header lines and the body. .IP "\(bu" 4 Make sure you save it as \s-1ASCII\s0 text. For example, if you are using Microsoft Word, use \*(L"Save As\*(R" and choose \*(L"Text Only with Line Breaks.\*(R" .IP "\(bu" 4 If you created the file on a Mac, be sure to upload it as text, i.e. \s-1CR\s0's translated. (Unix computers have different codes denoting the end of a line than Mac's do, so your file might look like one long line to the Unix computer.) .PP Within these guidelines there is a lot of flexibility. You can put Bcc:, X\-Face:, or any other header in the headers. You can put things like Cc: [yourname] in the headers. Be creative. Just don't put anything in there you wouldn't want your webmaster to see, because that's where bounced messages go. .PP Now go ahead and upload your e\-mail template to the \s-1WWW\s0 server and look at it with your \s-1WWW\s0 browser. .SS "Put a link to the template on your page." .IX Subsection "Put a link to the template on your page." Here's an example: .PP Would you like to cross the bridge? Download my \*(L"questions three\*(R" form and send it to . .PP Even after you create your \s-1WWW\s0 form, you will want to leave this link in to increase accessibility to users with disabilities. .SS "Decide if a mailto: link will do." .IX Subsection "Decide if a mailto: link will do." Already, without any complicated \s-1HTML,\s0 you have a way for people on the \s-1WWW\s0 to send you the information you want. Before you go to the effort of making an \s-1HTML\s0 form, decide if it's really worth it. Forms on the \s-1WWW\s0 have two particular disadvantages: .IP "\(bu" 4 You will get a lot of frivolous e\-mail from people who are merely ``surfing the web.'' .IP "\(bu" 4 The user's e\-mail address is typed manually, and is often mistyped, so that you have no way to reply. This is less of a problem with mailto: links. .SS "Create the \s-1HTML\s0 form." .IX Subsection "Create the HTML form." If you've decided to create an \s-1HTML\s0 form, you need to give people a way to supply an e\-mail address. With the mailto: link, their mailer would supply the From: address for them. But now you need to add a line to the top of your e\-mail template like this: .PP .Vb 1 \& From: [email] .Ve .PP Here is an example \s-1HTML\s0 form. .PP .Vb 1 \& Your e\-mail address: _\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_ \& \& Your name: _\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_ \& \& Your quest: _\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_ \& \& Your favourite colour: _\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_ \& \& Send e\-mail (This example doesn\*(Aqt actually send e\-mail.) .Ve .PP This is the \s-1HTML\s0 source: .PP .Vb 2 \&
\& \& Your e\-mail address:

\& Your name:

\& Your quest:

\& Your favourite colour:

\& \&

.Ve .PP This is a very simple example. Note that the \s-1NAME\s0 of each input corresponds to what you previously put in the e\-mail template. In this example they are email, yourname, quest, and colour. This is the key concept in using cgiemail. Be careful to make them exactly the same; if you put NAME=\*(L"colour\*(R" in your \s-1HTML\s0 form and [color] (note the spelling difference) in your e\-mail template, the input will not show up in the e\-mail. .SS "Create more advanced \s-1HTML\s0 forms." .IX Subsection "Create more advanced HTML forms." To learn to create more complicated forms, read \s-1NCSA\s0's guide. All of their example forms can be converted to cgiemail forms merely by changing the \s-1ACTION.\s0 Unlike other forms-to-email programs, you are not required to use hidden inputs with special names. .PP All types of inputs (radio buttons, etc.) work the same way. Each input needs a \s-1NAME,\s0 and that name must appear within square brackets in your e\-mail template. It's that simple. To get more ideas, see the cgiemail example page. .SS "Make sure the \s-1ACTION\s0 is correct." .IX Subsection "Make sure the ACTION is correct." The trickiest part of the \s-1HTML\s0 form is getting the \s-1ACTION\s0 set correctly. Start with the \s-1URL\s0 of your e\-mail template, then split it into two parts, e.g. .PP .Vb 3 \& http://web.mit.edu/wwwdev/cgiemail/questions3.txt \& \e /\e / \& \`\-\-\- Part 1 \-\-\-\*(Aq \` \-\-\-\-\-\-\-\- Part 2 \-\-\-\-\-\-\-\-\-\-\*(Aq .Ve .PP Then you put the script name in the middle. Usually this is ``/cgi\-bin/cgiecho'', but it depends on how your server is configured. On web.mit.edu it happens to be ``/bin/cgiecho'', thus my \s-1ACTION\s0 looks like this: .PP .Vb 3 \& http://web.mit.edu/bin/cgiecho/wwwdev/cgiemail/questions3.txt \& \e /\e /\e / \& \`\-\-\- Part 1 \-\-\-\*(Aq script name \` \-\-\-\-\-\-\-\- Part 2 \-\-\-\-\-\-\-\-\-\-\*(Aq .Ve .PP For simplicity, you may leave out part 1, but you must include it if you want to test your form as a local file. If you don't know what that means, just feel free to omit part 1. .SS "Try out your form with cgiecho." .IX Subsection "Try out your form with cgiecho." Pop your form into your favorite \s-1WWW\s0 browser, fill in the inputs, and submit it. You should see what the processed form looks like. If instead you see an error with a number near 500, your \s-1ACTION\s0 is probably set wrong. Go back to the previous step. .PP If some of your inputs don't seem to be showing up in the processed form, make sure that the inputs have the exact same names in the \s-1HTML\s0 form as in the \s-1ASCII\s0 template. E.g. NAME=\*(L"yourname\*(R" in the \s-1HTML\s0 form and [yourname] in the e\-mail template. .SS "Go live with cgiemail." .IX Subsection "Go live with cgiemail." Now change cgiecho to cgiemail in the \s-1ACTION\s0 of your \s-1HTML\s0 form. Try it out. You should receive an e\-mail message with the processed form. If you get a success page but don't receive mail, there is some problem with your template file. Go back and make sure you correctly followed the guidelines in step 1. .PP If it works, congratulations! .PP 9. Debug if you don't get mail .PP Normally, mail gets sent asynchronously, meaning it goes into a queue to be sent at at a convenient time. Asynchronous mail is sent more efficiently and reliably, but has the disadvantage that problems can only be reported by mailing an error message back to the sender. To the mail system, it appears that the sender of the mail is the web server, so the error message won't get to you. .PP If you aren't getting mail, you can temporarily use synchronous mail delivery by creating a hidden input named cgiemail-mailopt and giving it a value containing \*(L"sync\*(R", e.g. .PP .Vb 1 \& .Ve .PP Note: For release 1.1, this won't work. Ask your webmaster to install a newer release. Some mailers have a nonstandard extension that sends bounces to an address in an Errors-To: header in addition to the web server. However, some errors make this header line unreadable, so there's no way to make absolutely sure the bounce will go to you. .SS "Optional: Add text to the success page." .IX Subsection "Optional: Add text to the success page." When mail is sent, a page titled ``Success'' appears with the text of the e\-mail message. You may use a hidden variable called ``addendum'' to add your own text. Here is a simple example: .PP .Vb 1 \& .Ve .PP If you are willing to assume that readers of your form are using recent browser software like Lynx 2.6 or Netscape 3.0, then you may put \s-1HTML\s0 markup into this variable using the appropriate character entities. For example, if you wanted to add .PP .Vb 1 \& Thank you! .Ve .PP then the \s-1HTML\s0 markup would be .PP .Vb 1 \& Thank you! .Ve .PP meaning you would need the following in your form: .PP .Vb 2 \& .Ve .PP Note that besides being difficult to write, this feature won't work for people using older browser software. .SS "Optional: Use an alternate success page." .IX Subsection "Optional: Use an alternate success page." If you don't like the default page that comes up when email is successfully sent, you can specify an alternate \s-1URL\s0 using a hidden variable called ``success'' in your \s-1HTML\s0 form, e.g. .PP .Vb 1 \& .Ve .PP Note: Start your \s-1URL\s0 with / or with http://. Otherwise cgiemail will direct your browser to a second invocation of cgiemail, resulting in the error No variable substitutions. .PP As of release 1.3, there is no way to make this alternate success page contain information the user submitted in the form. This feature is likely to be added in a future release. .SS "Optional: Make some inputs required." .IX Subsection "Optional: Make some inputs required." If you would like to automatically reject forms with certain inputs left blank, add the prefix ``required\-'' to the name of the input in both your \s-1HTML\s0 form and your e\-mail template. Here is an example: .PP In the \s-1HTML\s0 form: .PP .Vb 1 \& Your name: .Ve .PP In the e\-mail template .PP .Vb 1 \& Your name: [required\-yourname] .Ve .SS "Optional: Specify formatting for some inputs." .IX Subsection "Optional: Specify formatting for some inputs." If, in your e\-mail template, the text inside square brackets begins with %, cgiemail will use the \fIprintf()\fR function in C on the field name after the comma. If you're not familiar with this function, look in a book on C. If you are familiar with it, please note these two differences: .IP "\(bu" 4 The first character in the format string must be %. .IP "\(bu" 4 Characters like \en and \et must be literal. If you want a newline, you have to put a newline just before the comma, even though this looks strange. For example, if Godzilla's Pizza wanted toppings listed one per line, they would put the following in their e\-mail template: .Sp .Vb 2 \& [%s \& ,topping] .Ve .SS "Optional: Use \s-1CGI\s0 environment variables." .IX Subsection "Optional: Use CGI environment variables." This feature may or may not work, depending on whether or not your webmaster enabled it when configuring cgiemail. .PP In addition to form inputs, your e\-mail template can include \s-1CGI\s0 environment variables simply by preceding the variable's name with a dollar sign. For example, .PP .Vb 1 \& [$HTTP_USER_AGENT] .Ve .PP will put the name of the user's browser and/or gateway in your e\-mail message. In order to be respectful of privacy, your \s-1HTML\s0 form should warn users about any information about them that will be included in the e\-mail, e.g. \s-1HTTP_USER_AGENT, REMOTE_ADDR.\s0 .SS "Administrivia" .IX Subsection "Administrivia" Upstream contact: cgiemail .PP Debian maintainer: Anibal Monsalve Salazar .PP Complete information on building, installing and using cgiemail is available on the \s-1WWW:\s0 .PP .Vb 1 \& http://web.mit.edu/wwwdev/cgiemail/ .Ve