Introduction
OlympusNet FormStork allows you to use HTML forms with your
OlympusNet hosted Web site, without having to do any kind of server-side
scripting to make your forms work. OlympusNet FormStork does the work
for you, so you can concentrate on making your site attractive and
useful.
Once your form is using OlympusNet FormStork, each form submission
will be automatically emailed to you.
Important Note: This documentation is for the
latest version of OlympusNet FormStork. If your domain is hosted on
satsop.olympus.net, use this
document instead.
Quick Start
To begin using OlympusNet FormStork immediately, follow these steps:
- Set the action for your form to use Formstork. A minimal form tag will look like:
<form action="/OlympusNet/FormStork">
Your form tag may also include other parameters, as desired.
- Add a hidden field to your form, as follows:
<input type="hidden" name="olympusnet_form_handler"
value="my form"> The value "my form" can be any name you
like.
- Upload a file named
httpforms.ini
to your home directory. This file must contain the following lines:
[my form]
smtp username = mailbox@example.com
smtp password = supersecret
email from = address@example.com
email to = other.address@example.com
In the above example, replace "my form" with whatever name you used
in the "olympusnet_form_handler" hidden input field, replace the
smtp username and password with your OlympusNet Mail login
information, and replace the email addresses with valid email
addresses of your choice (the two addresses may be the same.)
That's all there is to it! Anytime someone submits your form, their
input will be emailed to the "email to" address you specify. Read on to
find out about all of the fancy configuration options that can be
added.
OlympusNet FormStork is configured by creating a file named
httpforms.ini in your home directory. This
is generally achieved by creating the form with a text editor, and
uploading it using an SFTP application.
- Sections
-
Your httpforms.ini file is
separated into sections, one section for each form
that you have configured. It is not strictly necessary to have
a separate section for each HTML form: each section can be used
by as many forms as you like. Forms that require different
handling will require their own section.
Sections in your httpforms.ini file
are specified by a name in square brackets, on a line by
itself:
[my form]
- Options
-
Every option that is added beneath the section name belongs
to that section (until a new section is defined.) Options for
each section are written:
option = value
- Indentation
-
All indented lines in your httpforms.ini
configuration file are treated specially: they are considered to be
continuations of the last option. Very long values, or lists of
multiple values can use indentation to ensure they get assigned to the
proper option:
[my form]
option =
value1
value2
The special treatment of indentation also implies that new options
must begin at the left edge of the page, unindented.
- Comments
-
Lines in your httpforms.ini file that begin
with a # symbol are ignored. This can be
used to write comments about your configuration options in the
httpforms.ini file itself.
[my form]
# Company policy, do not change:
option = value
- The
defaults section
-
There is one section name that is special, the name
[defaults]. Items in your
[defaults] section apply to
all of your other sections, unless those sections
explicitly override the default options. The Examples chapter describes some
possible uses for the [defaults]
section.
Your HTML form must be edited in order to work with OlympusNet
FormStork. The changes that are required are:
- The
action attribute
-
The action taken when someone submits your form must be set to
use OlympusNet FormStork. This is done by setting the
action attribute of your form tag to the
OlympusNet FormStork URL:
<form action="/OlympusNet/FormStork">
Your form tag may also include any other HTML attributes, such
as method or enctype.
- The
olympusnet_form_handler field
-
Your form must contain a field, typically a "hidden" field,
named olympusnet_form_handler. This field tells OlympusNet FormStork
which section in your configuration file to
use for this form:
<input type="hidden" name="olympusnet_form_handler" value="my form">
Important: The name "my form" can be any name
you like, so long as it exactly matches the name as it is written
in your httpforms.ini file. The names of
your sections are case-sensitive, so "my form" is
considered a different name than "My Form", or "MY FORM".
General Options
Options in your httpforms.ini file are
separated into two types: general options, described in this section,
and email options, described in the next
section. General options apply to the entire section in which they appear.
General options are as follows:
- show errors
-
The show errors option tells OlympusNet
FormStork whether or not to report configuration errors when a
form is submitted. Usually, these errors are not something you
want to show to people who submit your form, but it is useful
to see these errors while testing your OlympusNet FormStork
configuration.
If this option is set to "yes", configuration errors will be
described in detail. If this option is set to "no", errors
which occur are not fully explained. It is set to "no" by
default.
show errors = yes
- smtp username
-
The smtp username option specifies the login
name to use for SMTP authentication when sending mail. This
should be the name of a mailbox hosted by OlympusNet.
[my form]
smtp username = mailbox@example.com
This option is required for all forms.
- smtp password
-
The smtp password option specifies the password
to use for SMTP authentication when sending mail. This should
be the password of the mailbox specified in the smtp
username option.
[my form]
smtp password = s3krit
This option is required for all forms.
- allowed urls
-
The allowed urls option specifies which form
URLs may submit forms using this section:
allowed urls =
http://www.example.net/form1.html
http://www.example.net/form2.html
By default, form submissions can originate from any URL.
This option can be used to restrict which forms may use your
OlympusNet FormStork configuration. This provides a measure of
control over your form submissions, but it should not be
considered 100% secure! If your form submissions
require strict acccess control, please use other authentication
mechanisms in addition to this one.
The URLs listed in this option must match exactly the URL
that is used to display the HTML form. If your form is accessed
from more than one URL, then each URL must be listed
separately.
- required
-
The required option describes which fields in
your HTML form must be filled in. The value of this option
should be a list of field names, one name per line. These names
must exactly match the names of the fields as they are written
in the HTML form:
# httpforms.ini file
[my form]
required =
First_Name
Email_Address
If a form submission is missing any required fields, an
error will be returned to the web browser. The error message
will specify the names of the missing required fields for the
user, so using descriptive field names will help the
automatically generated error message to be clear. Field names
will be written with spaces replacing underscore characters in
the message, for convenience.
- validate as email
-
The validate as email option specifies which
input fields must contain valid email addresses when they are
submitted:
[my form]
validate as email = Email_Address
If a form submission contains a validated field which does
not contain a valid email address, an error will be returned to
the web browser. The error message will specify the names of
the invalid fields for the user, so using descriptive field
names will help the automatically generated error message to be
clear. Field names will be written with spaces replacing
underscore characters in the message, for convenience.
This option is particularly useful when an input field will
be used as recipient address for one of your configured emails.
For more information on this feature, see Substitutions, below.
- max field size
-
The max field size option allows you to set a
limit on the size of input for your text (or textarea) fields.
The value for this option must be an integer representing the
maximum number of characters (letters, numbers, spaces, etc.)
that will be submitted for any one field:
[my form]
max field size = 200
Submitted values that are longer than the maximum allowed
size will be truncated to the size you specify. The default
value for this field is 2048 characters. You may restrict it
further by setting your own value, but values larger than the
default will be ignored.
- max file size
-
The max file size option allows you to set a
limit on the size of files submitted in any file upload fields.
The value for this option must be an integer representing the
maximum file size in Megabytes (MB)
[my form]
max file size = 2
If a form submission contains a file upload that is larger
than the maximum allowed size, and error will be returned to
the web browser. The error message will specify the name of
the first file that is too large.
The default value for this field is 40 Megabytes. You may
restrict it further by setting your own value, but values
larger than the default will be ignored. If the email
attachments option is set to "no" for all emails
triggered by a form, this option is ignored.
- error template
-
When errors are detected in a form submission, for example
when a required field is left blank, an error report is
displayed to the user. By default, this error report is very
plain. The error template option allows you to
create a custom HTML page for displaying these errors. The
value of the error template option is the
relative path to the template file in your home
directory:
[my form]
# The leading slash is optional
error template = /templates/form_errors.html
In your custom error template, the exact errors are
displayed where you specify, using Substitutions. The substitution
for displaying error messages is
%(error_messages)s:
<div>
<!-- Display error messages here: -->
%(error_messages)s
</div>
This substitution must be used in your custom template in
order for input errors to be visible to people submitting your
form.
- success template
-
When a form submission is successful, a success message is
displayed to the user. By default, this message is very plain.
The success template option allows you to create a
custom HTML page to be returned to the user after a successful
form submission. The value of the success template
option is the relative path to the template file in
your home directory:
[my form]
# The leading slash is optional
success template = /templates/form_success.html
- failure template
-
When there are errors in your OlympusNet FormStork
configuration, the form submission fails and a failure message
is returned to the user. By default, this failure message is
very plain. The failure template option allows you
to create a custom HTML page to be returned to the user in the
case of a configuration failure. The value of the failure
template option is the relative path to the
template file in your home directory:
[my form]
# The leading slash is optional
failure template = /templates/form_failures.html
At first glance, this option looks similar to the error template
option. The difference is this: the error
template is for displaying errors made by the
users of your form. The failure template
is for displaying a general failure message when an error in
your configuration prevented the form from being
successfully processed.
If the show errors
option is set to "yes", the configuration failure is explained
in detail, and the failure template option is
ignored.
Remember, to avoid revealing private information about your
configuration to people using your forms, and to ensure that
your failure template is used, reset show
errors = no when you are done testing your
configuration!
Email Options
OlympusNet FormStork accepts submissions for your HTML forms, and
generates one or more email messages that you configure. Email options
apply to one email message within a configured section. Email options are written:
email_name option = value
The email_name can be any word that begins with
"email", including the word email by itself.
Each different email_name that you use represents a
different email to send when your HTML form is submitted:
email1 option = value
email2 option = value
For each email that you have configured, both a "From" address and a
"To" address (or a "Cc" or "Bcc" address) must be specified.
These are the only two required options in your configuration.
- email from
-
The email from option specifies the sender address
for this email. The sender address should be written exactly as
you would like it to appear in the "From:" header of your
email:
[my form]
email from = "My Form" <address@example.com>
The email from option must contain a valid email
address. If your email cannot be delivered for some reason, this
is the address it will be returned to.
- email to
-
The email to option specifies one or more
recipients of this email. The recipient addresses should be
written exactly as you would like them to appear in the "To:"
header of your email. Specify multiple recipients one per line
(remember to indent subsequent
lines:
[my form]
email to =
"Jane Doe" <address@example.com>
"John Doe" <address1@example.com>
The email to option must contain at least one
valid email address. Invalid address lines will be ignored when
sending the mail, but will still be added to the "To:" header
of the email.
- email cc
-
The email cc option specifies one or more
carbon copy recipients of this email. The recipient addresses
should be written exactly as you would like them to appear in
the "Cc:" header of your email. Specify multiple recipients
one per line:
[my form]
email cc =
"Jane Doe" <address@example.com>
"John Doe" <address1@example.com>
Invalid address lines will be ignored when sending the mail,
but will still be added to the "Cc:" header of the email.
- email bcc
-
The email bcc option specifies one or more
blind carbon copy recipients of this email. Specify multiple
recipients one per line:
[my form]
email bcc =
address@example.com
address1@example.com
Invalid addresses will be ignored when sending the mail.
- email subject
-
The email subject option specifies a "Subject:"
header for your email. The default subject is "Form
Submission".
[my form]
email subject = New Signup From example.com
- email body
-
The email body option allows you to specify the
text of the email to send. By default, the text is a plain list
of form field names from your HTML form, each followed by the
user input for that field. Your custom message can include the
values entered by the user in your HTML form by using substitutions, which are
described in detail below, but here's a quick preview:
[my form]
email body =
Attention:
Please contact %(Customer_Name)s at %(Phone_Number)s
The email body option is useful for short and
simple messages, but it has several limitations, due to it
being part of the configuration file itself:
- Leading indentation is removed from the beginning of each line.
- Empty lines are removed entirely.
- Non-ASCII characters are stripped from the text.
If you require more exact formatting for your email text, see
the email template option, which does not suffer from
the above limitations.
- email template
-
The email template option specifies a file to
use as the body of your email. The value of the email
template option is the relative path to the
template file in your home directory:
[my form]
# The leading slash is optional
email template = /emails/message1.txt
As with the email body option above, your
email template file may include substitutions.
If this option is specified, the email body
option is ignored.
- email attachments
-
The email attachments option controls whether
or not the contents of file upload fields are attached to the
email. If this option is set to "no", the uploaded files will
not be attached to the email. It is set to "yes" by
default.
[my form]
email1 attachments = yes
email2 attachments = no
- email max size
-
The email max size option allows you to set a
limit on the total size of the email. The value for this option
must be an integer representing the maximum email size in
Megabytes (MB):
[my form]
email max size = 2
The default value for this field is 50 Megabytes. You may
restrict it further by setting your own value, but values
larger than the default will be ignored.
- email optional
-
The email optional option can be used to
designate an email message as optional. Normally, at least one
valid recipient must be found for each email you have
configured, or the form submission will fail. If this option is
set to "yes", the email will instead be ignored if no valid
recipient addresses are found. Combined with substitutions, this can be used
to provide users of your form with the option to receive an
email.
[my form]
email2 to = %(Customer_Email)s
email2 optional = yes
Substitutions
Your form configuration items, such as the email body
or even email to can include values that are submitted in
the form being processed, using substitutions. A substitution
is specified by:
- A % character
- The name of the field to include, in parentheses
- A single letter, usually an s
The above items must be written as a single word in the order listed
above. To repeat our earlier example:
[my form]
email body =
Attention:
Please contact %(Customer_Name)s at %(Phone_Number)s
In the above example, %(Customer_Name)s will be
replaced with the user's input for the Customer_Name form field,
and %(Phone_Number)s will be replaced with the user's
input for the Phone_Number field. There are many more advanced
formatting tricks that can be used with substitutions. For details
on advanced formatting methods, see the documentation for the
Python programming language's String
Formatting Operations, which OlympusNet FormStork
substitutions are based on.
Note that if you wish to include a literal %
sign in your text, it must be doubled to avoid being
interpreted as the start of a substitution:
[my form]
email body =
%(Customer_Name)s was 100%% satisfied
Examples
Some configuration examples:
-
Send a confirmation letter to the person filling out your form:
# OlympusNet FormStork configuration file
[my form]
smtp username = me@example.com
smtp password = supersecret
# Send one email to myself
email1 from = me@example.com
email1 to = me@example.com
# Send a confirmation letter to the customer
email2 from = me@example.com
email2 to = %(Customer_Email)s
email2 body = Thank you, your form has been submitted.
email2 attachments = no
# Make sure there is a valid email address to send the confirmation letter to
required = Customer_Email
validate as email = Customer_Email
-
Include an optional form field for an email address to receive a confirmation letter:
# OlympusNet FormStork configuration file
[my form]
smtp username = me@example.com
smtp password = supersecret
# Send one email to myself
email1 from = me@example.com
email1 to = me@example.com
# Send a confirmation letter, if the customer enters an address
email_confirmation from = me@example.com
email_confirmation to = %(Customer_Email)s
email_confirmation body = Thank you, your form has been submitted.
email_confirmation attachments = no
email_confirmation optional = yes
# Validated if entered, but not required.
validate as email = Customer_Email
-
In addition to other form processing, alert an administrator whenever any form is submitted. Also, use the same SMTP authentication for all emails:
# OlympusNet FormStork configuration file
[defaults]
# Notify the administrator
email_administrator from = me@example.com
email_administrator to = admin@example.com
email_administrator body = A form has been submitted for example.com
email_administrator attachments = no
smtp username = me@example.com
smtp password = supersecret
[my form]
# Send one email to myself for this form
email1 from = me@example.com
email1 to = me@example.com
[my other form]
# Send one email to someone else for this form
email1 from = me@example.com
email1 to = other@example.com
|
![[OlympusNet Logo]](http://www.olympus.net/ONet_images/ONetLogo_sm.jpg)