Ricochet

Ricochet is a CGI program that acts as an interface for the server's sendmail function; its purpose is to email data collected from a form to a specified address. At its most simple, a few lines of code can be added to an existing form, and Ricochet will send the unformatted data from the form to an email address. If  the email needs to have a particular layout or if a form field needs to be required, a Format file will be needed. If a personalized successful completion confirmation page for the end user is needed, then a Return Message file is required.

Note: Ricochet can be used with the RedDot Content Management System as long as the site is being published to cavern.uark.edu. For instructions, see the RedDot and Ricochet section below.

Form File

Start with the form file composed in HTML. This is the actual page that will be accessed on the Web and submitted with completed form elements. The opening <FORM> tag on this page will need to be altered to point to Ricochet. For Ricochet to work, there must also be the following input tags of the type "hidden". These lines of code should not wrap.

Note: The entries in bold need to be changed to match your form and configuration. The FORM name should be a unique value, but it will not show on the page.

At this point the form should work. Put in some test values and send it. The address VALUE specified in NAME="EMAIL_TO" should receive an email with the test values listed alphabetically by Input Field Names. You can stop here, or you can set up a personalized Return Message file.

Return Message File

To set up a Return Message file, change the VALUE of RETURN_MSG from "DEFAULT" to either "LOCATION" or "PATH" (see example below).  Also, create a web page with your message and save it into the account with the form.  Change the <INPUT> statement to tell Ricochet where the Return Message is, and upon a successful submission, the end user will be directed to the specified file. 

If LOCATION: is used you will not be able to use the feature to <INSERT> data from the form into the Return Message (see below). To use LOCATION: an absolute URL must be provided. Make sure to type a space after the colon and before your URL.
Example:

<INPUT TYPE="hidden" NAME="RETURN_MSG" VALUE="LOCATION: http://cavern.uark.edu/dept/return.html">

If PATH: is used, a complete path from the root of the server must be provided. Make sure to type a space after the colon and before your path.
Example:

<INPUT TYPE="hidden" NAME="RETURN_MSG" VALUE="PATH: /export/home4/ARSC/someone/public_html/return.html">

Note: The entries in bold need to be changed to match your configuration.
Note: To find the complete path from the root of the server, log into the account using SSH.
On cavern.uark.edu or comp.uark.edu, type:
pwd
and press Enter and the path will be returned.  Then add the complete file name so that it resembles the examples above.

The Return Message can be customized to show the end user the information they just submitted in the form, allowing them to print a copy (this feature is only available when using the PATH: value type).  This can be done using <INSERT> tags and the form field names from your form.
For example, in the HTML code of the Return Message you could have:

Thank you <insert name="name"> for completing our form.  You sent the following information:
<insert name="email_address"><br>
<insert name="home_address"><br>
<insert name="phone_number"><br>

Note: The entries in bold need to be changed to be the form field names used in your form.

You can stop here, but if you want to customize the look of the email sent, you can create and configure a Formatting file.

Format File

This file allows for the configuration the text formatting in the email sent when the form is submitted.  Without a format.dat file the email will list the data alphabetically by field name. Create the format file with any text editor or  SSH into the account and use the Pico command to create a new file; in either case it must be saved with the ".dat" extension (i.e. format.dat).

The Format file can also make a field required to be filled before the form can be sent. Add the statement:
FUNC="CHECK"
into the <INSERT> tag.  In the example below, the "name" field is required.  If the user leaves this field blank, he/she will get a message that the field needs to be filled before the form is sent.

In the Format file, use <INSERT> tags with the NAME of the form fields and plain text returns to control the layout.  There shouldn't be any HTML tags in the format. dat file.

For Example, this could be the entire code of the Format file (the INSERT statements will be replaced with the form data when the email is sent):

Name: <INSERT NAME="name" FUNC="CHECK">
Email: <INSERT NAME="email">
Choose Only One: <INSERT NAME="choice">
Choose As Many As You Like:<INSERT NAME="many1">
<INSERT NAME="many2">
<INSERT NAME="many3">
Their comments: <INSERT NAME="comment">

For the Format file to work with Ricochet, the FORM input tag's VALUE must be changed to "FILL", and another hidden INPUT will need to be added to tell Ricochet the path to the format.dat file (an absolute URL cannot be used here; it must be the complete path from the server's root). Previously, if a Format file was not being used, the VALUE was set to "LIST".

Example:

<INPUT TYPE="hidden" NAME="FORM" VALUE="FILL">
<INPUT TYPE="hidden" NAME="FORMAT_FILE" VALUE="/export/home4/ARSC/someone/public_html/format.dat">

Note: The path in bold needs to be changed to the path for your format.dat file.
Note: To find the complete path from the root the server, log into the account using SSH.
On cavern.uark.edu or comp.uark.edu, type:
pwd
and press Enter and the path will be returned.  The complete file name will need to be added so that it resembles the example above.

Using Ricochet with the RedDot Content Management System (CMS)

Ricochet can be used with the RedDot CMS with additional considerations.

• You can take an existing form and turn it into a RedDot template for the form page with hidden INPUT fields. See the example template below.
• You must know the location where the page will be published so that you can give the complete path (from the server root) for the Format file and the Return file.
• You must be able to assign your Return file a file name, for example "return.htm".

For assistance, contact Ken Muessig at kmuessi@uark.edu or 575-2901.

RedDot using Ricochet example form template

This is an example template. The highlighted objects are elements of RedDot that need to be designated as listed below the example.
Note: The lines of code should not wrap.

The following elements should be defined as type Standard Field:
<%email_to%>
<%email_subject_line%>
<%problem_contact_person%>
<%path_to_format_file%>
<%path_to_return_msg%>

The <%format_file%> element should be defined as type Media.  It is the element to which you will attach the format.dat file.

The <%form_body%> element should be defined as type Text.  This is where the text and form fields of your form will go.

The <%return_msg%> element  should be defined as type Anchor. Check Yes for the property insert path or filename only; this will stop RedDot from putting "http://" in front of what it sees as a link.

Note that:
<!-- <%format_file%> -->
<!-- <%return_msg%> -->
are commented out using <!-- -->.  To be published, these files have to be attached to the live template. So that they do not show up on the published page, they are commented out.