Description
This module can be used to collect user input via a web form and receive the filled form via email. The email can be sent to any registered Wikidot users.
Attributes
| attribute | required | allowed values | default | description |
|---|---|---|---|---|
| to | no | user names | site admins | comma-delimited list of Wikidot user names |
| button | no | any string | "send" | text displayed within the send button |
| format | no | "csv" | none | chooses alternative format of serializing the form data |
| title | no | text | "Wikidot.com - MailForm form data" | title of the email containing the submitted form |
| successPage | no | valid page name | none | after the form is sent the browser will be redirected to the specified page. put a "thank you" there if you wish ;-) |
The names of the 'to' recipients may not contain spaces: to specify a user name that has spaces, replace each space with a hyphen or underscore. If you do not specify a 'to' argument, the email will be sent to all site admins.
The definition of the form must be enclosed within the [[module … ]] … [[/module]] tags. The full specification of how to do this:
The definition of the fields is a nested list that looks like this:
# field1_name
* option1_name: value
* option2_name: value2
* suboption1_nam: value
# field2_name
* ...| option name | required | allowed values | default | description |
|---|---|---|---|---|
| title | no, but recommended! | any string | field_name | title of the field displayed in the same row on the left |
| type | no | text, textarea, select, checkbox | text | type of the input field |
| size | no | integer | 30 | size of the input field |
| default | no | value of the input | none | in case of the "text" or "textarea" fields it is just a string that appears inside the field; in case of "select" it must be one of the option labels |
| hint | no | any text | none | |
| options | only for "select", see below | |||
| rules | validation rules, see below | |||
"Select" type
If your field is a "select" field, you must also provide options for it. Do so as shown:
# field_name
* title: Gender
* type: select
* default: male
* options:
* male: Male
* female: Female
* option_name: Displayed valuewhere the "default: …" is not required, but if provided it should match one of the names of the options.
Validation
This module offers a powerful way to validate the input data. To use validation do:
# field_name
* title: Validated field
* type: text
* rules:
* rule1_name: value
* rule2_name: valuewhere rules are:
| rule name | allowed values | description |
|---|---|---|
| required | anything, e.g. "true" | if the field is required |
| minLength | integer | does not allow strings shorter than limit |
| maxLength | integer | does not allow strings longer than limit |
| match | perl regular expression | checks the value against expression, e.g. /[a-z0-9]+/ allows only lowercase letters and numbers |
| number | anything, e.g. "true" | checks if numeric |
| minValue | number | for numerical fields sets the lower limit |
| maxValue | number | for numerical fields sets the upper limit |
Examples
Ok, suppose you are making some kind of conference registration and want to grab participants' data:
[[module MailForm title="New message from MailForm documentation page"]]
# name
* title: Your name
* type: text
* rules:
* required: true
# affiliation
* title: Institute/Organization/Company
* hint: leave blank in none
# address
* title: Address
* rules:
* required: true
* minLength: 2
# address2
* title: Address (cont.)
# country
* title: Country
* rules:
* minLength: 2
# phone
* title: Phone
# email
* title: Email
* type: text
* rules:
* match: /^[_a-zA-Z0-9-]+(\.[_a-zA-Z0-9-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+$/
# payment
* title: I will pay by
* type: select
* options:
* creditcard: Credit card
* banktransfer: Bank wire transfer
* desk: At the registration desk
* na: Not applicable
# logging
* title: Please find me a hotel
* type: checkbox
* hint: we will contact you via email if yes
# comments
* type: textarea
* title: Extra comments
* rules:
* maxLength: 500
[[/module]]Note: The following image depicts the output of the prior MailForm code and is non-interactive.
