"Fossies" - the Fresh Open Source Software Archive

Member "formmail_compat-3.14c1/EXAMPLES" (11 Aug 2004, 16209 Bytes) of package /linux/www/old/formmail_compat-3.14c1.tar.gz:


The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 
    2 This file contains some examples of ways to install and
    3 configure NMS FormMail.pl.  It is intended to be read in
    4 conjunction with the README file.
    5 
    6 Here's what the configuration section of the FormMail.pl
    7 script looks like:
    8 
    9 
   10   # USER CONFIGURATION SECTION
   11   # --------------------------
   12   # Modify these to your own settings. You might have to
   13   # contact your system administrator if you do not run
   14   # your own web server. If the purpose of these
   15   # parameters seems unclear, please see the README file.
   16   #
   17   BEGIN
   18   {
   19     $DEBUGGING         = 1;
   20     $emulate_matts_code= 0;
   21     $secure            = 1;
   22     $allow_empty_ref   = 1;
   23     $max_recipients    = 5;
   24     $mailprog          = '/usr/lib/sendmail -oi -t';
   25     $postmaster        = '';
   26     @referers          = qw(dave.org.uk 209.207.222.64 localhost);
   27     @allow_mail_to     = qw(you@your.domain some.one.else@your.domain localhost);
   28     @recipients        = ();
   29     %recipient_alias   = ();
   30     @valid_ENV         = qw(REMOTE_HOST REMOTE_ADDR REMOTE_USER HTTP_USER_AGENT);
   31     $locale            = '';
   32     $charset           = 'iso-8859-1';
   33     $date_fmt          = '%A, %B %d, %Y at %H:%M:%S';
   34     $style             = '/css/nms.css';
   35     $no_content        = 0;
   36     $double_spacing    = 1;
   37     $wrap_text         = 0;
   38     $wrap_style        = 1;
   39     $send_confirmation_mail = 0;
   40     $confirmation_text = <<'END_OF_CONFIRMATION';
   41   From: you@your.com
   42   Subject: form submission
   43 
   44   Thank you for your form submission.
   45 
   46   END_OF_CONFIRMATION
   47   #
   48   # USER CONFIGURATION << END >>
   49   # ----------------------------
   50   # (no user serviceable parts beyond here)
   51 
   52 
   53 That can be quite scary to look at first thing in the morning,
   54 but fortunately many of those settings deal with specialized
   55 features that most people won't use, so you'll probably only
   56 need to change a few lines.
   57 
   58 Everyone will need to ensure that $mailprog, @referers and
   59 @allow_mail_to are set correctly.  These are described in
   60 detail in the README file.
   61 
   62 It is good practice to also set $postmaster to a valid email
   63 address, so that you recieve bounce messages if something goes
   64 wrong with the delivery of the email.
   65 
   66 
   67 EXAMPLE 1: A simple feedback form
   68 
   69 This example assumes that you have a single feedback form on
   70 your home page at the address <http://www.your.domain/homepage/>
   71 in which people can enter their name and favorite animal, and
   72 you want all the results to be mailed to you at the address
   73 <your-name@your.domain>.
   74 
   75 First, find out the location of the sendmail binary from your
   76 system administrator or hosting provider.  For this example,
   77 I'll assume that the sendmail binary is at /usr/sbin/sendmail.
   78 
   79 Now edit the configuration part of FormMail.pl.  The lines that
   80 need to be changed for this example are:
   81 
   82     $mailprog          = '/usr/sbin/sendmail -oi -t';
   83     $postmaster        = 'fred@your.domain';
   84     @referers          = qw(www.your.domain);
   85     @allow_mail_to     = qw(your-name@your.domain);
   86 
   87 So the configuration section should now look like:
   88 
   89 
   90   # USER CONFIGURATION SECTION
   91   # --------------------------
   92   # Modify these to your own settings. You might have to
   93   # contact your system administrator if you do not run
   94   # your own web server. If the purpose of these
   95   # parameters seems unclear, please see the README file.
   96   #
   97   BEGIN
   98   {
   99     $DEBUGGING         = 1;
  100     $emulate_matts_code= 0;
  101     $secure            = 1;
  102     $allow_empty_ref   = 1;
  103     $max_recipients    = 5;
  104     $mailprog          = '/usr/sbin/sendmail -oi -t';
  105     $postmaster        = 'fred@your.domain';
  106     @referers          = qw(www.your.domain);
  107     @allow_mail_to     = qw(your-name@your.domain);
  108     @recipients        = ();
  109     %recipient_alias   = ();
  110     @valid_ENV         = qw(REMOTE_HOST REMOTE_ADDR REMOTE_USER HTTP_USER_AGENT);
  111     $locale            = '';
  112     $charset           = 'iso-8859-1';
  113     $date_fmt          = '%A, %B %d, %Y at %H:%M:%S';
  114     $style             = '/css/nms.css';
  115     $no_content        = 0;
  116     $double_spacing    = 1;
  117     $wrap_text         = 0;
  118     $wrap_style        = 1;
  119     $send_confirmation_mail = 0;
  120     $confirmation_text = <<'END_OF_CONFIRMATION';
  121   From: you@your.com
  122   Subject: form submission
  123 
  124   Thank you for your form submission.
  125 
  126   END_OF_CONFIRMATION
  127   #
  128   # USER CONFIGURATION << END >>
  129   # ----------------------------
  130   # (no user serviceable parts beyond here)
  131 
  132 
  133 Here is an example of what the HTML source for the form might
  134 look like:
  135 
  136 
  137 <?xml version="1.0" encoding="iso-8859-1"?>
  138 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  139     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  140 <html xmlns="http://www.w3.org/1999/xhtml">
  141 <head>
  142  <title>What is your favorite animal ?</title>
  143  <link rel="stylesheet" type="text/css" href="/css/nms.css" />
  144 </head>
  145 <body>
  146  <form method="post" action="/cgi-bin/FormMail.pl">
  147   <table>
  148    <tr>
  149     <td>What is your name ?</td>
  150     <td><input type="text" name="name" /></td>
  151    </tr>
  152    <tr>
  153     <td>What is your favorite animal ?</td>
  154     <td><input type="text" name="animal" /></td>
  155    </tr>
  156    <tr>
  157     <td colspan="2"><input type="submit" /></td>
  158    </tr>
  159   </table>
  160  </form>
  161 </body>
  162 </html>
  163 
  164 
  165 One thing that I've glossed over here is style sheets.  You
  166 may have noticed that both the FormMail.pl configuration
  167 section and the example HTML above refer to a style sheet
  168 called "/css/nms.css".  
  169 
  170 Style sheets are files which tell browsers how to format
  171 and display HTML.  They're particularly good for scripts
  172 like FormMail.pl because they allow you to alter the look
  173 of the HTML that the script produces just by altering the
  174 style sheet, with no need to edit the guts of the script.
  175 See <http://www.w3.org/Style/CSS/> for more information
  176 on style sheets.  
  177 
  178 If you don't want to use style sheets on your site, then
  179 you can prevent FormMail.pl from using them by changing
  180 
  181     $style             = '/css/nms.css';
  182 
  183 to
  184 
  185     $style             = '';
  186 
  187 in the configuration section of the script.
  188 
  189 
  190 EXAMPLE 2: Setting the email subject
  191 
  192 If you test the example above, you'll notice that the email
  193 has the subject "WWW Form Submission".  This example extends
  194 example 1 by adding a customized email subject line.
  195 
  196 No further change to FormMail.pl is required, we just add an
  197 extra line to the HTML form.  The new line is
  198 
  199   <input type="hidden" name="subject" value="Favorite Animal" />
  200 
  201 With this line added, the HTML now looks like:
  202 
  203 <?xml version="1.0" encoding="iso-8859-1"?>
  204 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  205     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  206 <html xmlns="http://www.w3.org/1999/xhtml">
  207 <head>
  208  <title>What is your favorite animal ?</title>
  209  <link rel="stylesheet" type="text/css" href="/css/nms.css" />
  210 </head>
  211 <body>
  212  <form method="post" action="/cgi-bin/FormMail.pl">
  213   <input type="hidden" name="subject" value="Favorite Animal" />
  214   <table>
  215    <tr>
  216     <td>What is your name ?</td>
  217     <td><input type="text" name="name" /></td>
  218    </tr>
  219    <tr>
  220     <td>What is your favorite animal ?</td>
  221     <td><input type="text" name="animal" /></td>
  222    </tr>
  223    <tr>
  224     <td colspan="2"><input type="submit" /></td>
  225    </tr>
  226   </table>
  227  </form>
  228 </body>
  229 </html>
  230 
  231 
  232 Since the subject is set in the HTML form rather than in the
  233 script itself, you can have many different forms on your site,
  234 each using a different subject for the email.
  235 
  236 
  237 EXAMPLE 3: Copies to multiple recipients
  238 
  239 This example extends example 2 by sending a copy of the
  240 email to each of two different addresses.  For this
  241 example, I'll assume that you want the mail sent to both
  242 <your-name@your.domain> and <your-name@somewhere-else.domain>.
  243 
  244 There are two different ways to do this, and I'm going to
  245 show the most secure way.  This approach keeps the email
  246 addresses out of the HTML, which is desirable because it's
  247 common practice for the senders of junk email (SPAM) to
  248 collect target email addresses from web sites.
  249 
  250 
  251   # USER CONFIGURATION SECTION
  252   # --------------------------
  253   # Modify these to your own settings. You might have to
  254   # contact your system administrator if you do not run
  255   # your own web server. If the purpose of these
  256   # parameters seems unclear, please see the README file.
  257   #
  258   BEGIN
  259   {
  260     $DEBUGGING         = 1;
  261     $emulate_matts_code= 0;
  262     $secure            = 1;
  263     $allow_empty_ref   = 1;
  264     $max_recipients    = 5;
  265     $mailprog          = '/usr/sbin/sendmail -oi -t';
  266     $postmaster        = 'fred@your.domain';
  267     @referers          = qw(www.your.domain);
  268     @allow_mail_to     = ();
  269     @recipients        = ();
  270     %recipient_alias   = (
  271        'animals' => 'your-name@your.domain,your-name@somewhere-else.domain',
  272     );
  273     @valid_ENV         = qw(REMOTE_HOST REMOTE_ADDR REMOTE_USER HTTP_USER_AGENT);
  274     $locale            = '';
  275     $charset           = 'iso-8859-1';
  276     $date_fmt          = '%A, %B %d, %Y at %H:%M:%S';
  277     $style             = '/css/nms.css';
  278     $no_content        = 0;
  279     $double_spacing    = 1;
  280     $wrap_text         = 0;
  281     $wrap_style        = 1;
  282     $send_confirmation_mail = 0;
  283     $confirmation_text = <<'END_OF_CONFIRMATION';
  284   From: you@your.com
  285   Subject: form submission
  286 
  287   Thank you for your form submission.
  288 
  289   END_OF_CONFIRMATION
  290   #
  291   # USER CONFIGURATION << END >>
  292   # ----------------------------
  293   # (no user serviceable parts beyond here)
  294 
  295 
  296 The lines that have changed from example 1 are:
  297 
  298     @allow_mail_to     = ();
  299 
  300 which has changed because the addresses mentioned in %recipient_alias
  301 below are automatically allowed, so we don't need to explicitly allow
  302 any addresses, and the single %recipient_alias line has become the 3
  303  lines:
  304 
  305     %recipient_alias   = (
  306        'animals'  => 'your-name@your.domain,your-name@somewhere-else.domain',
  307     );
  308 
  309 which tells FormMail.pl that when you tell it that the
  310 recipient is "animals" via a hidden form field, you really
  311 mean that the recipients are those two addresses.
  312 
  313 The HTML form now has a hidden "recipient" input with a value
  314 of "animals":
  315 
  316 
  317 <?xml version="1.0" encoding="iso-8859-1"?>
  318 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  319     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  320 <html xmlns="http://www.w3.org/1999/xhtml">
  321 <head>
  322  <title>What is your favorite animal ?</title>
  323  <link rel="stylesheet" type="text/css" href="/css/nms.css" />
  324 </head>
  325 <body>
  326  <form method="post" action="/cgi-bin/FormMail.pl">
  327   <input type="hidden" name="subject" value="Favorite Animal" />
  328   <input type="hidden" name="recipient" value="animals" />
  329   <table>
  330    <tr>
  331     <td>What is your name ?</td>
  332     <td><input type="text" name="name" /></td>
  333    </tr>
  334    <tr>
  335     <td>What is your favorite animal ?</td>
  336     <td><input type="text" name="animal" /></td>
  337    </tr>
  338    <tr>
  339     <td colspan="2"><input type="submit" /></td>
  340    </tr>
  341   </table>
  342  </form>
  343 </body>
  344 </html>
  345 
  346 
  347 EXAMPLE 4: Multiple forms with different recipients
  348 
  349 This example adds an additional form to the same site, this
  350 time asking people about their favorite plant.  The results
  351 of this form get mailed to a new address, <foo@your.domain>.
  352 
  353 An extra line in the %recipient_alias part tells FormMail.pl
  354 how to handle a recipient value of "plants":
  355 
  356     %recipient_alias   = (
  357        'animals' => 'your-name@your.domain,your-name@somewhere-else.domain',
  358        'plants'  => 'foo@your.domain',
  359     );
  360 
  361 Putting all that together, the configuration section of the
  362 script is now:
  363 
  364 
  365   # USER CONFIGURATION SECTION
  366   # --------------------------
  367   # Modify these to your own settings. You might have to
  368   # contact your system administrator if you do not run
  369   # your own web server. If the purpose of these
  370   # parameters seems unclear, please see the README file.
  371   #
  372   BEGIN
  373   {
  374     $DEBUGGING         = 1;
  375     $emulate_matts_code= 0;
  376     $secure            = 1;
  377     $allow_empty_ref   = 1;
  378     $max_recipients    = 5;
  379     $mailprog          = '/usr/sbin/sendmail -oi -t';
  380     $postmaster        = 'fred@your.domain';
  381     @referers          = qw(www.your.domain);
  382     @allow_mail_to     = ();
  383     @recipients        = ();
  384     %recipient_alias   = (
  385        'animals' => 'your-name@your.domain,your-name@somewhere-else.domain',
  386        'plants'  => 'foo@your.domain',
  387     );
  388     @valid_ENV         = qw(REMOTE_HOST REMOTE_ADDR REMOTE_USER HTTP_USER_AGENT);
  389     $locale            = '';
  390     $charset           = 'iso-8859-1';
  391     $date_fmt          = '%A, %B %d, %Y at %H:%M:%S';
  392     $style             = '/css/nms.css';
  393     $no_content        = 0;
  394     $double_spacing    = 1;
  395     $wrap_text         = 0;
  396     $wrap_style        = 1;
  397     $send_confirmation_mail = 0;
  398     $confirmation_text = <<'END_OF_CONFIRMATION';
  399   From: you@your.com
  400   Subject: form submission
  401 
  402   Thank you for your form submission.
  403 
  404   END_OF_CONFIRMATION
  405   #
  406   # USER CONFIGURATION << END >>
  407   # ----------------------------
  408   # (no user serviceable parts beyond here)
  409 
  410 
  411 Finally, the HTML form for the plants page will look like
  412 this:
  413 
  414 
  415 <?xml version="1.0" encoding="iso-8859-1"?>
  416 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  417     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  418 <html xmlns="http://www.w3.org/1999/xhtml">
  419 <head>
  420  <title>What is your favorite plant ?</title>
  421  <link rel="stylesheet" type="text/css" href="/css/nms.css" />
  422 </head>
  423 <body>
  424  <form method="post" action="/cgi-bin/FormMail.pl">
  425   <input type="hidden" name="subject" value="Favorite Plant" />
  426   <input type="hidden" name="recipient" value="plants" />
  427   <table>
  428    <tr>
  429     <td>What is your name ?</td>
  430     <td><input type="text" name="name" /></td>
  431    </tr>
  432    <tr>
  433     <td>What is your favorite plant ?</td>
  434     <td><input type="text" name="plant" /></td>
  435    </tr>
  436    <tr>
  437     <td colspan="2"><input type="submit" /></td>
  438    </tr>
  439   </table>
  440  </form>
  441 </body>
  442 </html>
  443 
  444 
  445 EXAMPLE 5: You want to be able to reply to the emails
  446 
  447 Suppose you have the setup in example 4 working, and you
  448 decide that you want to ask the visitors to the Favorite
  449 Plant page for their email address in the form, and have
  450 FormMail.pl use the address that they enter as the
  451 'From' address for the email, so that you can hit 'reply'
  452 in your mail software to mail the visitor and strike up a
  453 conversation about their favorite plant.
  454 
  455 FormMail will do this automatically so long as the input
  456 where the visitor sets their email address is given the
  457 name "email".  If the input where the visitor gives their
  458 name is called "realname" then FormMail will use this as
  459 the comment part of the email address.
  460 
  461 No change is needed to FormMail.pl for this example, we
  462 just add an "email" field to the form and rename the
  463 "name" input to "realname":
  464 
  465 
  466 <?xml version="1.0" encoding="iso-8859-1"?>
  467 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  468     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  469 <html xmlns="http://www.w3.org/1999/xhtml">
  470 <head>
  471  <title>What is your favorite plant ?</title>
  472  <link rel="stylesheet" type="text/css" href="/css/nms.css" />
  473 </head>
  474 <body>
  475  <form method="post" action="/cgi-bin/FormMail.pl">
  476   <input type="hidden" name="subject" value="Favorite Plant" />
  477   <input type="hidden" name="recipient" value="plants" />
  478   <table>
  479    <tr>
  480     <td>What is your name ?</td>
  481     <td><input type="text" name="realname" /></td>
  482    </tr>
  483    <tr>
  484     <td>What is your email address ?</td>
  485     <td><input type="text" name="email" /></td>
  486    </tr>
  487    <tr>
  488     <td>What is your favorite plant ?</td>
  489     <td><input type="text" name="plant" /></td>
  490    </tr>
  491    <tr>
  492     <td colspan="2"><input type="submit" /></td>
  493    </tr>
  494   </table>
  495  </form>
  496 </body>
  497 </html>
  498 
  499 
  500 NOTES
  501 
  502 There are many more configuration options for FormMail.pl
  503 than those used in these examples.  See the README file for
  504 details.
  505 
  506 In all these examples, I've left the value of the $DEBUGGING
  507 configuration variable set to 1.  It should be changed to 0
  508 once you have finished setting up your forms, in order to
  509 restrict the amount of information that a malicious person
  510 attacking your site can obtain.
  511 
  512 In all these examples, I've left the value of the
  513 $max_recipients configuration variable set to the default
  514 of 5.  Since the largest number of recipients used in any
  515 single form in these examples is 2, it could be reduced to
  516 2 and all of the examples would continue to work.
  517