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,66 @@
+# 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

[Vasily Kuznetsov, 2019/01/23 12:23:13]

Nit: let's rename the file to `handler1-log.csv`, i think it makes it a bit more
clear that it's the log of handler1 and that the file format is CSV.

[rhowell, 2019/01/23 21:40:26]

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

[Vasily Kuznetsov, 2019/01/23 12:23:13]

Nit: here we can also rename the template file to make its name a bit more
telling. Maybe something like formmail/handler1/mail-template.tmpl -- how does
this look?

[rhowell, 2019/01/23 21:40:26]

Done.

+
+The `handler1.fields.xxx` subgroup includes the descriptions of the form fields,
+and these must match the fields on the form. These are the fields expected in the
+POST request and then made available to the template. Each variable in the group
+defines a field and its value can be:
+* "mandatory" (which makes the field mandatory)
+* and/or "email" (which makes the field an email)
+* or it can be empty (just a normal optional field).
+
+For mandatory fields we can also define "group-name.fields.field-name.mandatory"
+to override the error message that will be returned by the handler if the field
+was empty. Likewise for email fields we can define
+"group-name.fields.field-name.email" to set the error message that's returned if
+the content of the field doesn't look like an email. See an example:
+
+    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