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

Delta Between Two Patch Sets: sitescripts/formmail/README.md

Issue 29984580: Issue 4413 - Merge formmail.py and formmail2.py (Closed) Base URL: https://hg.adblockplus.org/sitescripts/
Left Patch Set: Start the README Created Jan. 18, 2019, 12:44 a.m.
Right Patch Set: Nits & formatting on README Created Jan. 23, 2019, 9:35 p.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « .sitescripts.example ('k') | sitescripts/formmail/template/eyeo.mail » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 # formmail 1 # formmail
2 2
3 This script generates a form and sends an email.? It provides the following URLs : 3 The web handler that extracts form data from a POST request, uses it to
Vasily Kuznetsov 2019/01/18 16:52:13 The script doesn't generate the form, it only acce
rhowell 2019/01/18 20:08:07 Done.
4 4 populate an email template and then sends the produced email to a configured
5 * */? 5 list of addresses.
6 6
7 ## Dependencies 7 ## Dependencies
8 8
9 * [Python 2.7](https://www.python.org/download/releases/2.7/) 9 * [Python 2.7](https://www.python.org/download/releases/2.7/)
10 * [mock](https://pypi.python.org/pypi/mock) (Only for the tests) 10 * [Jinja2](http://jinja.pocoo.org/docs/2.10/intro/)
11 * _Anthing else?_ 11 * Other packages are required for testing, please see the list of 'deps' in
Vasily Kuznetsov 2019/01/18 16:52:13 The handler also uses Jinja2 for rendering the tem
rhowell 2019/01/18 20:08:07 Done.
12 [`tox.ini`](../../tox.ini)
12 13
13 ## Running the script 14 ## Running the web handler
14 15
15 The script can be run as a module, using the following command: 16 Normally, the formmail web handler is run by the multiplexer, and configured
Vasily Kuznetsov 2019/01/18 16:52:13 formmail.py is not really a standalong script, it'
rhowell 2019/01/18 20:08:07 Done.
17 via the sitescripts config file. Please refer to the main
18 [README](../../README.md) for more information about the multiplexer and
19 configuring `sitescripts.ini`.
16 20
17 ```commandline 21 In order to activate this handler, add the following line to the multiplexer
18 sitescripts.formmail.web.formmail.sendMail 22 config file:
19 ```
20
21 The script can also be run directly from the file, using:
22 ```commandline
23 python sitescripts/formmail/web/formmail.py
24 ```
25
26 ## Configuration
27
28 The handler is configured via sitescripts config. In order to activate this
29 handler, add the following line to multiplexer config:
30 23
31 [multiplexer] 24 [multiplexer]
Vasily Kuznetsov 2019/01/18 16:52:13 This part should probably be in # Running the web
rhowell 2019/01/18 20:08:07 Done.
32 sitescripts.formmail.web.formmail = 25 sitescripts.formmail.web.formmail =
33 26
34 Its own configuration is in the section `formmail`: 27 ## Configuring the web handler
28
29 `formmail.py` can handle multiple URLs and forms. Each URL will correspond to a
30 group of config variables that all start with the same prefix, for example:
31 handler1. These variables are configured in the [formmail] section of the
32 config file.
33
34 The URL of the form, where the POST request comes from:
35 35
36 [formmail] 36 [formmail]
Vasily Kuznetsov 2019/01/18 16:52:13 This part will need more explanation. I think we s
rhowell 2019/01/18 20:08:07 I'm still not exactly clear what the `.fields` sec
Vasily Kuznetsov 2019/01/21 13:54:17 The form itself is usually another page, so its be
rhowell 2019/01/22 22:53:54 Ahh, gotcha. Makes sense. Thank you for the very c
37 test.csv_log = /var/log/something.csv_log 37 handler1.url = formmail/test/apply/submit
38 test.url=test/apply/submit 38
39 test.template=formmail/test/template/test.mail 39 The CSV file into which all submissions will be saved (optional):
40 test.fields.email=mandatory, email 40
41 test.fields.email.mandatory=You failed the email test 41 handler1.csv_log = /var/log/handler1-log.csv
42 test.fields.email.email=You failed the email validation 42
43 test.fields.non_mandatory_email=email 43 The Jinja2 template for the email. This is where the recipient email addresses
44 test.fields.non_mandatory_message= 44 are entered.
45 test.fields.mandatory=mandatory 45 [(See an example email template here.)](formmail/test/template/test.mail)
46
47 handler1.template = formmail/handler1/mail-template.tmpl
48
49 The `handler1.fields.xxx` subgroup includes the descriptions of the form
50 fields, and these must match the fields on the form. These are the fields
51 expected in the POST request and then made available to the template. Each
52 variable in the group defines a field and its value can be:
53 * "mandatory" (which makes the field mandatory)
54 * and/or "email" (which makes the field an email)
55 * or it can be empty (just a normal optional field).
56
57 For mandatory fields we can also set "group-name.fields.field-name.mandatory"
58 to override the error message that will be returned by the handler if the field
59 was empty. Likewise for email fields we can define
60 "group-name.fields.field-name.email" to set the error message that's returned
61 if the content of the field doesn't look like an email. See an example:
62
63 handler1.fields.email = mandatory, email
64 handler1.fields.email.mandatory = You failed the email test
65 handler1.fields.email.email = You failed the email validation
66 handler1.fields.non_mandatory_email = email
67 handler1.fields.non_mandatory_message =
68 handler1.fields.mandatory = mandatory
LEFTRIGHT

Powered by Google App Engine
This is Rietveld