Customer Resources

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

Form Handler (Form to Mail)

Basic Instructions

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.

Advanced options

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.

Parameter Help

The main parameters used are as follows:

The following optional parameters may also be used:

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)#

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.

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:

Testing

Troubleshooting

This help file supplied by RE-ENTITY DESIGN.


SiteWinder WebSite Administration Server v3.01, © MetaWerx 1997-2014. All rights reserved.