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.
Quick Start
To begin using OlympusNet FormStork immediately, follow these steps:
- Set the action for your form to point at OlympusNet FormStork. A minimal form tag will look like:
<form action="http://satsop.olympus.net/form_handlers/email_handler/submit">
Your form tag may also include other parameters, as desired.
- Add two hidden fields to your form, as follows:
<input type="hidden" name="olympusnet_form_handler" value="my form">
<input type="hidden" name="olympusnet_domain" value="example.com">
The value "my form" can be any name you like. Replace "example.com" with the name of your domain
- Upload a file named
.htforms
to your Web site's top-level directory. This file must contain the following lines:
[my form]
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, 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
.htforms in the top-level directory of
your web space. This is generally achieved by creating the form with a
text editor, and uploading it using an FTP application.
- Sections
-
Your .htforms 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 .htforms 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 .htforms
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 .htforms file that begin
with a # symbol are ignored. This can be
used to write comments about your configuration options in the
.htforms 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="http://satsop.olympus.net/form_handlers/email_handler/submit">
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 .htforms file. The names of
your sections are case-sensitive, so "my form" is
considered a different name than "My Form", or "MY FORM".
- The
olympusnet_domain field
-
Your form must also contain a field, typically a "hidden" field,
named olympusnet_domain. This field
specifies the domain where your OlympusNet FormStork configuration file can be
found:
<input type="hidden" name="olympusnet_domain" value="example.com">
Usually the olympusnet_domain will be the same domain
your HTML form is found in. However, if you have more than one
domain hosted on OlympusNet, the olympusnet_domain field
can specify a configuration in a different domain, if desired. Note
that only domains whose Web sites are hosted on OlympusNet are
allowed to access your OlympusNet FormStork configuration.
General Options
Options in your .htforms 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
- allowed domains
-
The allowed domains option specifies which domains,
other than your own domain, may submit forms using this
section:
[my form]
allowed domains =
example.net
example.org
Other domains that are permitted access to your configuration
must be hosted on OlympusNet. Any HTML page from the listed
OlympusNet-hosted domains, or any of their OlympusNet-hosted
subdomains, is granted permission to use that section of your
OlympusNet FormStork configuration to process input.
By default, only pages in the same domain as your OlympusNet
FormStork configuration are permitted to use the configuration to
process form submissions.
- allowed urls
-
The allowed urls option specifies which form URLs,
other than URLs in your own domain, may submit forms using this
section:
allowed urls =
http://www.example.net/form1.html
http://www.example.net/form2.html
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.
Other URLs that are permitted access to your configuration
must be hosted on OlympusNet.
- 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:
# .htforms 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
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
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.
-
- 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 web 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 web
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 web
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 web 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]
# 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]
# 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:
# 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
[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)