Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Unified Diff: sitescripts/formmail/README.md

Issue 29984580: Issue 4413 - Merge formmail.py and formmail2.py (Closed) Base URL: https://hg.adblockplus.org/sitescripts/
Patch Set: More work on README Created Jan. 22, 2019, 10:52 p.m.
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « .sitescripts.example ('k') | sitescripts/formmail/template/eyeo.mail » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
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`,
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
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
« no previous file with comments | « .sitescripts.example ('k') | sitescripts/formmail/template/eyeo.mail » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld