FormHandler Servlet
This is a guide to installing the FormHandler Servlet for use on your website.
The first section covers a basic installation and will create a working form-mailer on your site. The advanced section covers templating options, automatic replies and other advanced features.
If you require any assistance using any of these resources, please contact support
The following code must be added to your ROOT/WEB-INF/web.xml file. Make sure you add it inside the <web-app> element. Remember to replace the parameters such as yourname@yourdomain.com with your own details. You can also change the name of the servlet. This can be anything you want but you must change the name in all three places in the xml below where you see MyTestForm. You must also change the action in your form on your web page. This is explained below.
<servlet> <servlet-name>MyTestForm</servlet-name> <servlet-class>com.metawerx.servlet.FormHandlerServlet</servlet-class> <init-param> <param-name>email</param-name> <param-value>yourname@yourdomain.com</param-value> </init-param> <init-param> <param-name>mailserver</param-name> <param-value>mail.metawerx.net;mail2.metawerx.net</param-value> </init-param> <init-param> <param-name>dnsservers</param-name> <param-value>resolver1.metawerx.net,resolver2.metawerx.net</param-value> </init-param> <init-param> <param-name>next</param-name> <param-value>http://yoursite/success.htm</param-value> </init-param> <init-param> <param-name>errors</param-name> <param-value>http://yoursite/errors.htm</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>MyTestForm</servlet-name> <url-pattern>/servlet/MyTestForm</url-pattern> </servlet-mapping>
This servlet (class file) goes in the ROOT/WEB-INF/classes/com/metawerx/servlet/ folder. After you have uploaded it, you will need to reload the application using the Tomcat Manager for changes to take effect. Reload the ROOT application. If the option to reload is not available, it is most likely you haven't added the above xml correctly to your web.xml file.
Now you can add the form you want to use to your web page. It must have the following basic attributes to work. The action attribute of the form element must be set with your domain name and end with the servlet name. Each element within the form must have the name attribute; fields can be named anything you like.
Example:
<form action="http://www.yoursite.com/servlet/MyTestForm" method="post"> Contact Name:<input name="contactname" type="text"> Email:<input id="email" name="email" type="text"> Enquiry:<textarea rows="6" cols="24" name="enquiry"></textarea> <input name="send" value="send" type="submit"> </form>
In this example, the servlet is mapped to /servlet/MyTestForm because of the url-pattern tag in the web.xml (see above). This can be renamed to anything you like. If renaming it, be sure to change it on the form, and the url-pattern in the XML, and to reload the application using the Tomcat manager after any changes to the XML.
For those who need more advanced options, such as an instant email reply or html templates, use this extended xml and refer to the detailed help below.
<servlet> <servlet-name>MyTestForm</servlet-name> <servlet-class>com.metawerx.servlet.FormHandlerServlet</servlet-class> <init-param> <param-name>email</param-name> <param-value>yourname@yourdomain.com</param-value> </init-param> <init-param> <param-name>mailserver</param-name> <param-value>mail.metawerx.net</param-value> </init-param> <init-param> <param-name>replyto</param-name> <param-value>#field(email)#</param-value> </init-param> <init-param> <param-name>replytoname</param-name> <param-value>#field(email)#</param-value> </init-param> <init-param> <param-name>next</param-name> <param-value>http://www.yourdomain.com/thankyou.htm</param-value> </init-param> <init-param> <param-name>errors</param-name> <param-value>http://www.yourdomain.com/error.htm</param-value> </init-param> <init-param> <param-name>subject</param-name> <param-value>YourSubject (#field(fullname)#)</param-value> </init-param> <init-param> <param-name>from</param-name> <param-value>youraddress@domain.com</param-value> </init-param> <init-param> <param-name>fromname</param-name> <param-value>Name to appear on Email as From Name</param-value> </init-param> <init-param> <param-name>template</param-name> <param-value>http://www.yourdomain.com/yourForm.htm</param-value> </init-param> <init-param> <param-name>template_html</param-name> <param-value>http://www.yourdomain.com/yourForm.htm</param-value> </init-param> <init-param> <param-name>r_template</param-name> <param-value>http://www.yourdomain.com/response.htm</param-value> </init-param> <init-param> <param-name>r_to</param-name> <param-value>#field(email)#</param-value> </init-param> <init-param> <param-name>r_from</param-name> <param-value>sales@yourdomain.com</param-value> </init-param> <init-param> <param-name>r_fromname</param-name> <param-value>YourName</param-value> </init-param> <init-param> <param-name>r_subject</param-name> <param-value>Thankyou for...</param-value> </init-param> <init-param> <param-name>required</param-name> <param-value>fullname;contactname;email;billingaddress1</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>MyTestForm</servlet-name> <url-pattern>/servlet/MyTestForm</url-pattern> </servlet-mapping>
You may also have several forms running at once. You'll need to duplicate the xml within web.xml and give the servlet a new name (in BOTH areas, the <servlet> tag <servlet-mapping> tag) and a new url-pattern. Also remember to reload the application each time you edit the xml, using the Tomcat manager.
The main parameters used are as follows:
mailserver: Set this to one or more valid SMTP email servers, to use when sending the email. If entering multiple servers, separate them with semicolons. If you are a metawerx customer, the metawerx redundant email servers may be used (mail.metawerx.net;mail2.metawerx.net).
dnsservers: Set this to one or more valid DNS servers to use to check email addresses are valid. If entering multiple servers, separate them with commas. If you are a metawerx customer, the metawerx redundant internal DNS servers may be used (resolver1.metawerx.net,resolver2.metawerx.net).
email: Your email address. You will be sent an email to this address each time a user submits the form. The address must be valid or the email will not be sent. Additional addresses can be specified using the optional cc parameters (see below).
next: The next page. After clicking Submit, the contents of this page are sent to the user (this must be specified as an absolute URL, or start with a leading slash or the servlet will try to load your page from the servlets folder. Example, use "/thanks.htm" or "/accounts/thanks.htm" instead of simply "thanks.htm").
errors: The errors page. After clicking Submit, if there is a problem sending the email, the user is sent to this page. The format is the same as the "next" page parameter.
The following optional parameters may also be used:
subject: Subject line to use on email (default is name of page). It is ok to use spaces in the subject and MHTML such as subject=Application from #field(UserFullName)#
from: From-address to be used (default is robot@metawerx.net). The address must be valid or the email will not be sent. It is ok to use MHTML here, such as from=#field(EmailAddress)# if the field on the form where the user enters their email address is named "EmailAddress"
fromname: From-address display name to be used (default is Form Submission)
replyto: Reply-To-address to be used (default is support@metawerx.net)
replytoname: Reply-To-address display name to be used (default is Metawerx Support)
template: URL of a page on your server, written in plain-text, to use as a template for sending the email. The template may contain placeholders to display the fields, for example: Dear Administrator, #field(fullname)# has sent an order. If no template is specified, the system will send an email that lists all fields, each on a separate line.
errors: URL of a page to display to the user if errors occur while sending email or with required fields. (hint: this is a quick way to verify the users email address was entered correctly, and show a page asking them to re-enter it in case of error). If no errors page is specified, the "next" page is sent to the user instead.
noheaders: Provide this parameter (noheaders=true) to true to strip the Date/Server/ClientIP and Form Name headers off emails that are sent to the main user. If not set, these headers are automatically attached at the top of each email (except for HTML-based emails).
onlysendifnoerror: Provide this parameter (with value of true) to ignore emails where the email-address field has errors, or the reply email could be sent. In high volume systems, this lowers the chance of receiving form spam (submissions that are not valid).
required: List of fields separated with semicolons. If provided, all these fields must be provided or the error page will be displayed and autoreply-email will not be sent. If onlysendifnoerror is also set, then no primary email will be sent either. eg: Email;RealName;Address;Country
Sending an Automatic Response to the user
Automatic responses can also be sent to the user who submitted the form.
To do this, all of the fields below must be specified.
Field values all allow placeholders to specify fields from the form, so it is possible to use values such as #field(EmailAddress)# in the Servlet Engine settings. eg: r_template=http://www.mysite.com/response.htm,r_to=#field(EmailAddress)#
r_template: URL of a page on your server, written in plain text, to use as a template for sending an automatic response back to the user who submitted the form. The template may contain field placeholders to display the fields from the form, for example: Dear #field(fullname)#, thankyou for your order. (if no template is specified, no automatic response is sent)
r_to: Address to send email to, typically this is #field(EmailAddress)# where "EmailAddress" is the name of the field on your form that contains the users address.
r_subject: Subject line to use on email. It is ok to use spaces and MHTML in the subject. For example: r_subject=Automatic Response for #field(UserFirstName)# #field(UserLastName)#
r_from: From-address to be used (this should be set to your email address). If the user replies to the email, replies will come to this address.
r_fromname: From-address display name to be used.
Sending HTML-formatted emails
Responses sent to the user, as well as to your email address, may also be formatted in HTML. This allow for a very professional HTML-based reply to be sent to the user after they submit your form.
To use this feature, the normal (plain-text) responses must be provided first. Some mail-clients do not allow HTML-based emails, so it is necessary to provide a plain-text version (template and r_template)
See the section below on MHTML-formatting for instructions on inserting the fields from the form into your emails. The HTML-formatted responses can be specified using the following optional parameters.
template_html: URL of a page written in HTML, to send to your email address in HTML-format
r_template_html: URL of a page written in HTML, to send to the users email address in HTML-format
Using MHTML in the settings and pages
MHTML extensions may be used inside the settings fields and also inside the pages that are displayed to the user. This feature allows you to personalise the responses to the user based on what they have entered on the form.
This can be used for the following powerful advantages:
Receive form submissions, using the Senders Email Address To do this, instead of using a from= parameter such as from=MyWebSite, use from=#field(email)# where "email" is the name of the field on your form where the user enters their email address. For example, if you are asking for the users email address in a field named "SubmitterEmail", use from=#field(SubmitterEmail)# and then all forms sent to you by email will appear to have come from the address the user entered in the SubmitterEmail field on your form.
Specify fields inside the Subject of your emails: This feature can be used to have customised subjects based on fields on the form. For example, if their is a field called "FullName" which you have asked the user to enter their full name in, you can customise the email-response to use a subject such as "Thankyou, #field(FullName)#, for your form submission!". To do this, set the r_subject field to r_subject=Thankyou #field(FullName)# for your form submission!
Using the users name inside the "next page" This feature can be used to thank the user personally for their submission on your "next page". To do this, in the HTML on your next page, you can specify the following text: <b>Thankyou #field(FullName)#, we will send the information you requested as soon as we have processed your details!</b>. This will be substituted as the page is displayed to the user, and the #field(FullName)# section will be replaced with whatever they entered into your form's "FullName" field.
Displaying errors in the "errors page" or "next page" This feature can be used to report a list of errors to the user upon failed submissions. To do this, in the HTML on your next page, you can specify the following text: <b>#field(errors)# This #field(errors)# section will be replaced with the list of errors which prevented the form mail from being sent.
Adding customised fields to Next Page and Error Page Another very useful feature, when a form is submitted, the next page is scanned for #field()# statements and filled in with fields from the form. This lets you say Thankyou #field(FullName)#, your application was accepted. The list of errors on error pages can also be output this way, using #field(formhandler_errors)#.
Formatting the emails which are sent to you This is one of the most useful features of FormHandlerServlet. When a form is submitted, the fields will come through in whichever order the server decides to list them in. However, using a template, you can provide a layout for the form submission. The following example demonstrates how to do this:
Template example (save this onto your server, and specify the URL with template=addressOfPage)
The following details were submitted: User name: #field(UserName)# Email address: #field(Email)# Comments: #field(Comments)# Postal Address: #field(AddressLine1)# #field(AddressLine2)# #field(City)#, #field(State)#, #field(PostCodeZip)# #field(Country)# Phone: #field(PhoneNumber)# Fax: #field(FaxNumber)#
The following extra fields are provided automatically, and can be used in the templated emails, pages or settings such as the Subject field on emails.
formhandler_referrer: Referring page - page that submitted to the FormHandler.
formhandler_server: Server name
formhandler_submitdate: Submission date
formhandler_clientip: Client IP address
formhandler_errors: List of errors from form, shows missing required fields and invalid email addresses. This field cannot be used in the settings or templates, only in the error page (which is set with the errors parameter).
Many other ideas are possible, use your imagination. For assistance, you may contact support@metawerx.net.
Testing
On the form you plan to use the Form Handler Servlet on, set the action line as follows:
<FORM ACTION=/servlet/MyFormName METHOD=POST>
Click Submit on your form. You should be taken to the page you specified in the next parameter, and should receive an email containing the details from the form submission.
If you need any help, contact support.
Troubleshooting
1. The servlet redirects the user to "/servlet/mypage.htm".
Solution: Change the "next" parameter in the settings to use an absolute URL such as "http://www.yoursite.com/pages/thanks.htm" or "/pages/thanks.htm".
2. The servlet redirects the user to my main root page.
3. The email is not arriving
b) check that the email address specified is valid. using a fake email address or an address that does not make sense will not work. eg: info@metawerx.net is a valid email address.
c) wait up to 5 minutes. Sometimes email servers take a while to pass the email to your final destination. Sometimes email will arrive immediately, sometimes it can take a few minutes. Emails can also arrive in a different order than which they were sent in.
4. When I use MHTML #field()# commands, problems occur.
b) Make sure you are including both # marks. #field() will not work. You must #field()#.
c) If the values are displaying as "null" instead of empty fields or values, then you have incorrectly specified a field name. Check the spelling carefully.
d) Page locations must be specified as absolute URL's if using MHTML, otherwise FormHandler will not process the page.
5. Even when an error occurs, my errors page is not showing.
6. When I reply to a form submission, it goes to the wrong address
7. I am receiving a blank email from my forms
8. I am receiving an email that says "The servlet has been accessed directly", with no other useful information.
9. The text from the Submit button is being added to the email (when not using a templated email).
If you need any help, contact support.
This help file supplied by RE-ENTITY DESIGN.
(* the MyFormName name should be set to whatever you named the servlet on the admin page.)
In this case, you have specified your next page as a relative URL, for example "mypage.htm". The servlet loads from the /servlet folder, so will try to load your page as /servlet/page.htm.
In this case, you have specified your next page incorrectly, and the servlet is sending the user directly to your servers root page (instead of showing an error).
a) check that you have specified the "email" and/or the "from" addresses in lower case. "Email" and "From" will not work, you must use the name in lower case. eg: email=address@server.com.
a) MHTML field names are case sensitive. Make sure you have specified these accurately. This is a common mistake. Take the time to double-check before contacting support.
a) check that you have specified the URL correctly.
b) Specify the page as an absolute URL (http://server/page, not just /page).
To send the response back to the user when you hit Reply in your mail program, make sure you specify the from= parameter as from=#field(EmailAddress)# where "EmailAddress" is the name of the field on your form where the user enters their email address
This will happen if you have provided an address of an email-template, but have not provided a template file, have incorrectly configured the address of the template file in the servlet settings, or have provided a blank file. Make sure your settings are correct, and try accessing your template using a web browser to make sure it looks right. (If it is a text-based template, use View Source to see the layout because it will look strange in a browser without paragraph and line breaks).
This will happen if you have forgotten to use a POST method on your form. Make sure your form tag has a method="POST" attribute. It can also happen if you don't put name attributes on any of your form elements. Make sure each form element contains a name="somename" attribute.
This can be eliminated by removing the name attribute on the Submit button.
SiteWinder WebSite Administration Server v3.01, © MetaWerx 1997-2014. All rights reserved.