formmail.pod - using and configuring fmail.pl
# Link .../cgi-bin/fmail.pl?form=formid
# Configuration [formid form] fields=field1,field2,... email=where.to@send.to query=querytemplate done=finaltemplate mail=mailtemplate
[formid formmail validation] field1_description=description of field1 field1_rules=rules... field1_required=1 field2_description=description of field2 field2_rules=rules...
# and templates, not shown here
fmail.pl provides the basic facilities of the original formmail.pl, with the following extras:
security - since the email to be sent to is stored in BSE's configuration, it cannot be hijacked to send email to others.
user information - since it's part of BSE it has access to BSE's user system, and can include information about the logged in member in the email if there is one.
validation - you can use the DevHelp validation engine to validate the fields the user enters
templates - the system uses BSE's templating system, allowing complete customization of the entry form, the final display form and the email sent
In general you want to link for fmail.pl and supply a form id:
<a href="/cgi-bin/fmail.pl?form=someform">Send us feedback</a>
You can also link without a form id:
<a href="/cgi-bin/fmail.pl">Send us feedback</a>
which is exactly the same as:
<a href="/cgi-bin/fmail.pl?form=default">Send us feedback</a>
If you make a modified query template, make sure you supply the form id as a hidden field:
<input type="hidden" name="form" value="<:id:>" />
During form processing, fmail.pl accepts 2 different action values:
a_send - send the email, assuming all fields pass validation. This will save the form data in the session object and refresh to a_done.
a_done - displays the completion page, using the values stored in the session. Note that this will only work for 10 minutes after submission to protect the users privacy.
Each form id refers to a form configuration section and a form validation section of the configuration file.
The configuration entries available in [form form] are:
query - the name of the query template, the form used to ask the user for their information. Default: formmail/defquery
done - the name of the final display template, used to thank them for entering their data or say it will be responded to, or whatever this form is being used for. Default: formmail/defdone
mail - the name of the email template, used to build the content sent
to the configured email address. If [mail].html_system_email is
non-zero and a template mail-template_html exists then a
multipart/alternative message will be sent. Default:
formmail/defemail.
fields - a comma separated list of fields to be entered. Default: from,subject,text
subject - the subject of the email sent. Default: User form emailed
email - the email address the form data is sent to. Defaults to the value configured as [shop].from or $SHOP_FROM from Constants.pm
send_email - if this is set to 0 then no email is sent. This can be used to avoid sending an email if you are using the sql option to send submitted form data to the database.
require_logon - if this is non-zero then the user must be logged on to display or submit the form. See also: logon_message.
logon_message - this message is displayed on the logon form if require_logon is set and the user isn't logged on.
autofill - if this is non-zero then form values which match the names of siteuser fields are defaulted on the form with the values from the currently logged in user. Default: Enabled. To disable add:
autofill=0
to the configuration area for your form.
encrypt - if this is non-zero then the emailed form data is encrypted using PGP or GPG as configured (see the crypt options below).
See ENCRYPTION for more information.
crypt_passphrase - the passphrase to the private key specified by crypt_signing_id. Only required if the encrypted email is to be signed. Default: $SHOP_PASSPHRASE from Constants.pm
crypt_signing_id - the key id to sign the encrypted message with. Default: $SHOP_SIGNING_ID from Constants.pm. eg. 564EB128
secure - if this is a true value then the formlink[] tags will use [site].secureurl to link to this form.
field_config - defines extra configuration values that will be loaded for each field. These values are accessible through the <:fields ...:> tag. Multiple names can be provided, comma separated.
sql - if this is set then it is treated an SQL statement that is executed when the form is successfully submitted. The parameters passed to the SQL statement are specified by the sql_params configuration value.
Typically this will be a SQL insert statement.
If this SQL statement fails to be prepared or fails to execute then form submission will fail.
By default this is executed against the configured BSE database, see the sql_dsn, sql_user, sql_password and sql_options to execute this against a different database.
sql_params - a comma separated list of fields to supply to the SQL given by sql.
If the field if of the form {field} then that field is extracted
from the currently logged on user.
If the field is of the form env{NAME} then the environment
variable called name will be used.
Otherwise it's taken as the name of one of the submitted form fields.
sql_dsn - if set this is the DBI DSN (see perldoc DBI) of database to execute the SQL configured by sql against.
See the documentation of the perl DBD driver for your database for information on defining a DSN.
sql_user - user to connect as if sql_dsn is set.
sql_password - password to connect with if sql_dsn is set.
sql_options - options to supply to the DBI connect method. This should be treated as a comma or equal sign delimited hash initializer:
sql_options=AutoCommit=1
spam_check_field - if non-empty then this form field is checked, if the value for this field is not present, or is non-empty then the actions defined for the form are silently ignored. Default: None.
log_spam_check_fail - if true then a message is written to STDERR - typically ending up in the server error log - when the checks described under spam_check_field fail. Default: true.
email_select - a semi-colon separated field name and configuration section to select an alternate email address from. Default: the email value or it's default is used. See ALTERNATE EMAIL ADDRESSES.
send_member_email - if this is set to non-zero and a site member is
logged on when the form is submitted successfully, an email with the
field values (but no attached files) is sent to the email address
configured to that member. This uses the template specified by
member_email_template. Default: 0 (no email sent to the member.)
member_email_template - the template base name used to render the
email. If the user doesn't have text only emails enabled, and a
template member_email_template_html exists then the email will
be multipart/alternative. Default: formmail/defemailcopy.
You can also configure information used for validation and available to the <:field ...:> tag in the templates. This is from the [formid formmail validation] section.
In general each entry is the name of a field (from fields above),
followed by underscore, followed by a validation configuration name,
for example from_required is used to configure whether the from
field is required.
fieldname_required - if this is non-zero the fieldname is a required field.
fieldname_required_if - a semi-colon separated list of other fields to check. Each entry can be a simple field name or a fieldname=value.
; name is required if the company or phone field is set name_required_if=company;phone
; email is required if contacttype is email email_required_if=contacttype=email phone_required_if=contacttype=phone
If you supply multiple fields to check against the then the field is required if any of the fields match:
; require phone if a contact type = phone or they have a company phone_required_if=contacttype=phone;company
fieldname_required_error - message displayed for the field if it's marked required but isn't set.
fieldname_description - a display name for the field.
fieldname_default - the default value for the field. For field with keys and display values, such as selects, this should be the key. For multiple select fields like checkboxes or multi-selects this should be the keys of the items to be selected separated by semi-colons (;).
fieldname_rules - a semi-colon separated list of validation rules
for the field. See the DevHelp::Validate manpage for a list of built-in rules,
some common ones are email, phone, weburl, date. You can
also configure extra rules, with some limits.
fieldname_htmltype - used by the default query form to choose how to display the field. Values accepted are "textarea", "password", "text", "select", "multiselect", "radio", "check", "file".
If this is set to "file" then this will be treated as a file upload.
Forms with file upload fields cannot be logged to the database.
fieldname_width - used by the default query form to set the width attribute for text, password and textarea fields.
fieldname_height - used by the default query form to set the height attribute for textarea fields.
fieldname_values - either the name of another configuration file section containing possible field values as keys and descriptions as values, or a semi-colon separated list of possible values. For example:
[someform formmail validation] ; shows as alpha, beta, gamma, selecting alpha returns a value of alpha ; beta as beta, gamma as gamma foo_values=alpha;beta;gamma ; shows as alpha, beta, gamma, selecting alpha returns a, beta b, gamma c bar_values=a=alpha;b=beta;c=gamma ; shows as One,Two,Three, selecting One return 1, Two 2, Three 3 quux_values=Quux Values
[Quux values] 1=One 2=Two 3=Three
This is used by the "select", "multiselect", "check" and "radio" htmltype values.
When specifying a section you can specify a prefix to allow for empty values:
foo_values=some section:prefix
[some section] prefix=None selected prefix1=One prefix2=Two
If fieldname}_values is "-sql" then the fieldname_values_sql is used to obtain the possible field values, and fieldname_values_group_sql is used to build the list of groups if option groups are used.
fieldname_groups - semi-colon separated list of option groups. Each entry is the label, '=', followed by a comma-separated list of values from fieldname_values.
fieldname_values_sql - SQL that returns values, this must return columns called id, label and optionally group_id, if fieldname_values_group_sql is used.
product_values=-sql product_values=<<SQL select id, title as "label", parentId as "group_id" from product pr, article ar where pr.articleId = ar.id and listed > 0 order by 2 SQL product_values_group_sql=<<SQL select id, title as "label" from article where parentId = 3 order by 2 SQL
fieldname_values_group_sql - see fieldname_values_sql.
fieldname_empty_groups - if true then empty groups will still be listed.
fieldname_maxfilesize - if the field has htmltype set to "file" then this is used to validate the size of the uploaded file.
fieldname_filetoobigmsg - if an uploaded file exceeds fieldname_maxfilesize then this message is returned as the field error. %s is replaced with the field description.
fmail.pl uses three templates:
query - asks the user for their information
mail - sents the information to you
done - displayed after the information is submitted.
Standard BSE dynamic tags are available on the query and done templates. Standard BSE static tags are available on the mail template.
These tags are available on all three templates:
id - the form id of the form
iterator begin fields ... iterator end fields - Iterates over the
fields in the order specified in the fields configuration value. Use
the field tag to get the field information. Other standard
iterator tags are also available, eg. field_count.
field fieldinfo - accesses information about the field, possible
values for fieldinfo include required, htmltype,
description and so.
On the mail and done templates fieldinfo can also be value to
present the value captured from the user.
For file fields fieldinfo can also be url (for the in-message
cid:... URL) or type for the MIME content type of the file.
iterator begin values ... iterator end values
On the query template - iterates over all of the possible values of the current field. See the fieldname_values configuration entry above.
On the email and done templates - iterates over the selected values of the current fields.
Use the value tag to get the value information.
value valueinfo - access information about a possible or selected
value, as set by the values iterator. Possible values for
valueinfo include id and name.
formcfg configkey
formcfg configkey default
Retrieves a value from the configuration file section for the form. This can be used to customize other values on a form basis without modifying the form template itself.
The following tags are available on the done and mail templates:
value fieldname - retrieves the value of a given field.
The following tags are only available on the query template:
error_img fieldname - displays an error icon if there was a validation error for that field.
msg - displays an error message
The following tags are only available on the mail template:
ifUser - check if a user was logged on when the form was submitted.
user userfield - access to the user's SiteUser record.
From release 0.15_08 of BSE the emails sent to the configured form address can be encrypted and optionally signed.
Warning: only the text content of the form email is encrypted, attached uploaded file will not be encrypted.
IT IS VERY IMPORTANT TO TEST A FORM IF ENCRYPTION IS ENABLED. TEST ALL CHANGES TO THE ENCRYPTION CONFIGURATION.
This is enabled by setting encrypt=1 in the [form form] configuration file section.
By default the same encryption settings as used for email will be used, but you can override these on a form basis.
To enable encryption of the email you must create a private key for the recipient of the email:
someuser$ gpg --gen-key
and follow the prompts.
Find the id of the key:
someuser$ gpg --list-keys /home/someuser/.gnupg/pubring.gpg ----------------------------- pub 1024D/FB26DB74 2005-04-06 Joseph Bloe <someuser@example.com> sub 1024g/5CC8431C 2005-04-06 [expires: 2006-04-06]
and then export it:
someuser$ gpg -a --export FB26DB74 >someuser.pubkey
You then need to take that file to the web server and import it into the public key-ring of the user that the web server software runs as:
webuser$ gpg --import someuser.pubkey
The simplest way to enable the key for use is to sign the key, since you may not want to make the signed key usable for others, you should lsign it:
webuser$ gpg --lsign-key FB26DB74
If you want the emails to be signed you will need to reverse this process, ie. create a private key for webuser, export it, import it to someuser.
If you don't want the email signed, set crypt_signing_id to empty:
crypt_signing_id=
If you do want the encrypted email signed you will need to set the signing id and the passphrase:
crypt_signing_id=5CC8431C crypt_passphrase=passphrase for private key
Problems with the encryption setup can be difficult to debug. Your first step should be to enable mail_encryption debugging:
[debug] mail_encryption=1
This will dump the HOME variable used, the gpg command used, and any output from GPG to stderr, which should then show in your web server error log.
If you see problems, first try disabling signing.
If you still have problems, try running the encryption command, but without the --no-tty command, providing some input. For example, if you see:
GPG command: gpg -aqe -r 'tony@develop-help.com' --no-tty
in the error log, try running:
echo something | gpg -aqe -r 'someuser@example.com'
This should give you some idea of what's needed. If you see:
Could not find a valid trust path to the key. Let's see whether we can assign some missing owner trust values.
No path leading to one of our keys found.
1024g/5CC8431C 2005-04-06 "Joseph Bloe <someuser@example.com>"
Fingerprint: 3F01 3589 BB4E 5D5B 9512 XXXX 063F DF74 5CC8 431C
It is NOT certain that the key belongs to its owner. If you *really* know what you are doing, you may answer the next question with yes
Use this key anyway?
Then you need to lsign this key, as above in Setting up GnuPG.
You can configure fmail to send form data to a database by setting the sql paremeter, for example, if you have 4 form parameters, email, name, organization, notes you could use:
sql=<<SQL
insert form_submissions(userid,email,name,organization,notes)
values(?,?,?,?,?)
SQL
sql_params={userId},email,name,organization,notes
Assuming a schema something like:
create table form_submissions (
id integer not null auto_increment,
email varchar(255) not null,
name varchar(255) not null,
organization varchar(255) not null,
notes text not null,
primary key(id)
);
You may want to disable sending the email as well:
send_email=0
Or send the data to some other database:
sql_dsn=dbi:DriverName:Parameters sql_user=database_user sql_password=database_password sql_options=AutoCommit=1
Forms with file upload fields cannot be logged to the database.
You can specify alternate email addresses for the email sent by a form with the email_select value:
[someform form] email_select=state;someform emails email=national@example.com [someform formmail validation] state_htmltype=select state_values=nsw=NSW;qld=Qld;nt=NT
[someform emails] nsw=nsw@example.com qld=qld@example.com ; nt uses default and goes to national address
Tony Cook <tony@develop-help.com>
$Revision$