Andrew Shearer

WebCarbon

Submit WYSIWYG Web Forms Through E-Mail

About WebCarbon

WebCarbon (previously called MailForm) is a handler for Web-based forms that sends an exact carbon copy of the form through e-mail, preserving all the HTML formatting of the original.

The result is readable in any HTML-aware e-mail program.

Any HTML Web form can be quickly adapted to use it, similarly to formmail.pl or FrontPage’s form to e-mail webbot, except the resulting e-mail isn’t text only.

The recipient of the e-mail may find it easier to read the form in HTML format with field positioning and labels intact, rather than see a text list of fields using internal HTML field names that aren’t visible on the original Web form. For large forms, forms whose fields haven’t all been given meaningful names, or forms using a grid format, WebCarbon is a huge help.

Additional features:

  1. Unlimited number of e-mail recipients
  2. User-specified recipients: If the form includes one or more e-mail address fields, the user can add to the recipient list. The form can also be set up to allow the user to modify the existing recipient list.
  3. E-mail template customization: The copies of the form sent through e-mail can be customized. They are based on a template that can be modified with any HTML editor, using the original form as a starting point. So they can include different headers or footers from the original, and buttons such as Submit can be removed. (In fact, any HTML form with fields named the same as the original form can be used as the e-mail template.)
  4. Chaining: Optionally, e-mail recipients themselves can make any desired changes to the form’s values and then click the form’s Submit button to resend the changed form, which can potentially use a different recipient list and template. Even though the next template may look the same, it can itself specify a different recipient list and different template for the next time. You can construct a preset document flow chain this way with an unlimited number of steps. New form fields can be introduced at each step. The e-mail users themselves don’t have to specify who the next recipients are.

How It Works

When the user submits the form from the Web, WebCarbon receives the names and values of the fields that the user filled in. It also receives hidden fields set by the Web author (which the end user cannot easily change), and this type of field is normally used to specify WebCarbon settings.

One of those settings indentifies an HTML template file, which at its most basic is a duplicate of the Web page containing the form: a page of blank fields. WebCarbon reads the template and substitutes each value the user entered into the fields of the template. WebCarbon uses this blank form template as a basis, but changes its HTML code so it recreates the field values the user saw just before submitting the form. It knows how to change the values of all the regular form elements: text fields, textarea fields, checkboxes, radio buttons, and select elements (also known as drop-downs, pop-up menus, list boxes, or pick lists).

Note that the original Web page and the HTML e-mail template are separate. WebCarbon never needs to read or locate the original Web page. So the form can be submitted from any type of page: an ASP page or an HTML e-mail message, for example. It reads only the template file and sends its filled-in version to the e-mail client. This means that the template has to be a regular HTML file: server-side code, such as SSI (server-side includes) and ASP code, won’t be processed.

WebCarbon e-mails the result to everyone on the recipient list (see the MailForm_To parameter) and sends the user’s browser to a confirmation page (see the MailForm_Confirm parameter).

If you are a web site administrator and your site does not already have WebCarbon installation, see the Installation Guide.

Authoring with WebCarbon

Construct the Web form in any HTML editor. Afterwards, there are just a few modifications to make so that its Submit button will send the values to WebCarbon and so that WebCarbon has a recipient list, subject, and template for the e-mail. The template is usually a copy of the the original form, but it has to be regular static HTML. WebCarbon won’t run any ASP code or server-side includes in the e-mail template. (You can include all you want in the original form on the Web, though, since WebCarbon doesn’t even look at that--it only sees the values the user submitted and merges them into the specifed template file.)

The exact steps are described below, but to summarize for the impatient, you will be setting the form action to /scripts/WebCarbon/WebCarbon.pycgi and adding hidden fields called MailForm_Subject, MailForm_To, MailForm_Confirm, and MailForm_TemplateURL. There are directions for graphical editors next, but if you’re comfortable with HTML code you switch into HTML view and use the code below.

For Graphical HTML Editors (FrontPage 2000)

These directions are written for FrontPage 2000. I’ll add directions for other editors later, but they will follow along the same lines.

  1. In FrontPage 2000, make sure you’re in Normal view (the tab at the bottom of the screen).
  2. Construct the form by adding items from the Insert menu’s Form submenu. You can use all of the choices: text boxes, checkboxes, radio buttons, and drop-down menus. Make sure to give each field or group of radio buttons a unique name, even if it’s only the numeric one that FrontPage assigns automatically.
  3. Make sure the insertion point is within the dashed-line boundaries of the form, then go to the Insert menu’s Form submenu and choose Form Properties.
  4. Under "Where to send results", choose "Send to Other" and then click the Options button at the bottom of the window. Now the dialog box that lets you set the form action will appear. Type /scripts/WebCarbon/WebCarbon.pycgi into the Action field, and make sure "POST" is chosen for the Method field. Then click OK. Keep the Form Properties dialog box open, though, because you’ll need it for the next step.
  5. Click Advanced (in the Form Properties dialog box). Here’s where you set the hidden fields that control WebCarbon. See the section below.

Hidden Fields

(These fields don’t really have to be hidden: you can make a regular text field with these exact names if you want the user to be able to change the value.)
NameValue
MailForm_ToRecipient’s e-mail address, such as jsmith5014@acme.com. For more than one recipient, you can either separate the addresses with a semicolon or include multiple MailForm_To fields.
MailForm_ConfirmThe URL of your confirmation page, to be displayed after the user submits the form. It should start with a slash, like /YourSiteFolderPath/YourConfirmationPage.html. (The reason for this is that MailForm_Confirm URL should normally be a site-relative path, beginning with a slash, specifying the Web page to appear after the form is submitted. If the URL is not site-relative or absolute, it will be interpreted as being relative to the script file, which is usually not what you want.)
MailForm_SubjectSubject line of the e-mail
MailForm_TemplateURL(WebCarbon only) A site-relative URL specifying the template file. This file must be placed inside a folder named _templates. (This is for security, so that WebCarbon can’t be asked to read arbitrary files inside the web root.) The _templates folder can be anywhere inside the Web root--IIS virtual directories won't work--but it's easiest to put it in the same folder as the original Web form. So, a sample directory structure: 
<web root>
    AFolder
        MyWebForm.html
<- user fills out this form on Web (can be ASP, PHP, etc.)
        _templates/
            MyWebForm.html
<- WebCarbon fills out this form to match and sends it through e-mail

For Raw HTML Coders

  1. Use these lines for your form tag, modifying the "value=" parameters to your own:
    <form action="/scripts/WebCarbon/WebCarbon.pycgi" method="post">
      <input type="hidden" name="MailForm_To" value="youremail@acme.com">
      <input type="hidden" name="MailForm_Confirm" value="/YourSiteFolderPath/YourConfirmationPage.html">
    (The MailForm_Confirm URL should normally be a site-relative path, beginning with a slash, specifying the Web page to appear after the form is submitted. If the URL is not site-relative or absolute, it will be interpreted as being relative to the script file, which is usually not what you want.)
  2. Examples of optional parameters:
      <input type="hidden" name="MailForm_Subject" value="Subject Line of the E-mail">
      <input type="hidden" name="MailForm_To" value="additionalEmailRecipient@acme.com">
      <input type="hidden" name="MailForm_To" value="aThirdEmailRecipient@acme.com">
  3. To have the email sent using the format of the original Web page, add the line
      <input type="hidden" name="MailForm_TemplateURL" value="</YourFolderPath/_templates/YourTemplateName.html">
    and make a copy of the form in the /YourFolderPath/_templates/ folder (using YourTemplateName.html for the filename).