Issue 4413 - Merge formmail.py and formmail2.py

sitescripts/formmail/README.md

Index: sitescripts/formmail/README.md
===================================================================
new file mode 100644
--- /dev/null
+++ b/sitescripts/formmail/README.md
@@ -0,0 +1,54 @@
+# formmail
+
+The web handler that extracts form data from a POST request, uses it to
+populate an email template and then sends the produced email to a configured
+list of addresses.
+
+## Dependencies
+
+* [Python 2.7](https://www.python.org/download/releases/2.7/)
+* [Jinja2](http://jinja.pocoo.org/docs/2.10/intro/)
+* Other packages are required for testing, please see the list of 'deps' in
+  [`tox.ini`](../../tox.ini)
+
+## Running the web handler
+
+Normally, the formmail web handler is run by the multiplexer, and configured
+via the sitescripts config file. Please refer to the main [README](../../README.md)
+for more information about the multiplexer and configuring `sitescripts.ini`.
+
+In order to activate this handler, add the following line to the multiplexer
+config file:
+
+    [multiplexer]
+    sitescripts.formmail.web.formmail =
+
+## Configuring the web handler
+
+`formmail.py` can handle multiple URLs and forms. Each URL will correspond to a
+group of config variables that all start with the same prefix, for example:
+handler1. These variables are configured in the [formmail] section of the
+config file.
+
+The URL of the form, where the POST request comes from:
+
+    [formmail]
+    handler1.url=formmail/test/apply/submit
+
+The CSV file into which all submissions will be saved (optional):
+
+    handler1.csv_log = /var/log/something.csv_log

[rhowell, 2019/01/18 20:08:07]

Does the spacing around the `=` matter? This is the only one with spaces.

[Vasily Kuznetsov, 2019/01/21 13:54:18]

AFAIK it doesn't. This is parsed by python ConfigParser and it seems to ignore
them. With this in mind, it probably makes sense to have spaces around "=" -- it
looks better this way and is easier to read.

[rhowell, 2019/01/22 22:53:54]

Done.

+
+The Jinja2 template for the email. This is where the recipient email addresses
+are entered. [(See an example email template.)](formmail/test/template/test.mail):
+
+    handler1.template=formmail/test/template/test.mail
+
+The `handler1.fields.xxx` subgroup includes the descriptions of the form fields:
+
+    handler1.fields.email=mandatory, email
+    handler1.fields.email.mandatory=You failed the email test
+    handler1.fields.email.email=You failed the email validation
+    handler1.fields.non_mandatory_email=email
+    handler1.fields.non_mandatory_message=
+    handler1.fields.mandatory=mandatory