FormMail Syntax

The configuration file is defined by a set of tags, similar to HTML tags. User input from submitting the form is available in variables.

Variables

Suppose you have a text input field in your original HTML form:

<input name="myname" id="myname" type="text" />

To refer to the value that the user types into this field, use $myname or ${myname}. In general, most everything in the configuration file starting with a dollar sign will be interpreted as a field value. If you really want to use a dollar sign, escape it with a backslash: \$

There are a few default variables, all of which start with $fm_

  • $fm_date​ - the current date
  • $fm_ip​ - the hostname or IP address of the submitter
  • $fm_all​ - a list of all form fields and submitted values
  • $fm_form - name of your form (from the configuration file)
  • $fm_config - full path to the configuration file
  • $fm_referer - URL to the HTML form
  • $fm_auth_bluestem_id - Bluestem ID of the submitter, if Bluestem authentication is used
  • $myname or ${myname}  - value of the myname input field

<!doctype> tag

The first line of your config file should be:

<!doctype form system 'FormMail-3.0.dtd'>

This tag has no closing tag.

<form> tag

Many of the tags in the configuration file will be placed within the <form> tag. 

Attributes

  • debug​ - this attribute will prevent any email from being sent, and will output diagnostics to your browser when you submit your form. It is highly encouraged for diagnosing why your form behaves as it does. If your configuration file contains syntax errors, they are reported to your web browser whether or not you have debug​ attribute set. This attribute is optional.
  • name="myform" - this attribute is required. It doesn't have to match the form name used in the form file.
  • contact="NetID@uic.edu" - email address to display if an error occurs. The default is the NetID@uic.edu of the owner of the configuration file.

Complete example

<!doctype form system 'FormMail-3.0.dtd'>
<form name="myform" contact="adabyron@uic.edu">
</form>

<format> tag

The <format> tag lets you reformat some of the input given by the user. This is useful for putting phone numbers in a standard format, or for removing non-numeric characters from what might be a nominally numeric input field. The re-formatting completely replaces each specified input field with a new value; the original value is lost. If FormMail can't figure out what the improved format should be, it leaves the original value alone. The <format> does not do any input validation, it just reformats. The reformatting action, when it occurs, happens before any input validation implied by any <validate> tags present. The format of this tag is:

<format name="field_name" vtype="format_type" if="if_cond">

Attributes

  • name="field_name" - field_name must match the name of an input field in your HTML form. This attribute is required and the value is case-sensitive.
  • vtype="format_type" - type of format
  • if="if_cond" - format action will take place only if if_cond evaluates to true.

Acceptable values for the vtype​ attribute include:

  • phone - Tries to produce a 10 digit phone number, of the form 312-996-1234. If 10 digits are specified, they are reformatted. If 5 digits starting with 3, 5, or 6 are specified, or if 7 digits starting with a campus prefix, it is assumed this is a UIC campus address and is turned into 10 digits. Otherwise the value is unchanged, but there may be some formatting to put hyphens in the right places.
  • digits - Non-numeric characters are stripped from the value
  • email​ - If an @ sign is present, the value is left alone. Otherwise, @uic.edu is appended to the value
  • NetID - Removes the string @uic.edu, if present at the end of the field.
  • newline - Replaces any newline in the string with a blank

Complete example

<!doctype form system 'FormMail-3.0.dtd'>
<form name="myform" contact="adabyron@uic.edu">
  <format name="phone_number" vtype="phone">
</form>

<validate> tag

You may want to establish some rules for accepting user input. For example, there may not be any point to accepting a submission unless an email or phone number is given. Each <validate> tag sets up a rule for a given input field. If the user violates any validate rule, he is told what the problem is, and instructed to return to the form, correct the error, and re-submit the form. The format is:
<validate name="field_name" public="pub_name" vtype="validation_type" if="if_cond">

At​tributes

  • name="field_name" - field_name must match the name of an input field in your HTML form. This attribute is required and the value is case-sensitive.
  • pub_name​ - pub_name is the name of the field that will be displayed if the input value does not validate.
  • vtype="validation_type" - type of validation
  • if="if_cond" - format action will take place only when if_cond evaluates to true.

Acceptable values for the vtype​ attribute include:

  • nonnull - The field must not be blank.
  • NetID - The field must contain 3-8 alpha-numeric characters, just like a UIC NetID. No guarantee that it is a bona fide NetID, and certainly no guarantee that it belongs to the submitter. This would typically be used to identify someone at UIC, since every real NetID is owned by a single person.
  • email​ - The field must look like an email address. Basically, this is something like logname@machine.domain. If there is no "@" sign, then "@uic.edu" is assumed. Note that only the form of the address is checked. The validity of the address is not checked. This would typically be used if you wanted to send mail to the client. The email address need not be one at UIC.
  • phone5 - The field must contain 5 or more digits. It may also contain other characters.
  • phone10 - The field must contain 10 or more digits. It may also contain other characters.
  • ​digits​ - The field may only contain digits.

Complete example​

<!doctype form system 'FormMail-3.0.dtd'>
<form name="myform" contact="adabyron@uic.edu">
  <validate name="email_address" public="Email address" vtype="email">
</form>

<auth> tag

The <auth> tag is used to force the submitter to authenticate via Bluestem, so the authenticated NetID can be recorded. I don't recommend this for sending email, because email is itself not secure, and it's hard to ensure that any email you receive was truly sent from FormMail. However, this tag will enforce the use of Bluestem, so if you save the form submission to a file, and the security on the files are acceptable, there is reasonable assurance that the submitter did use the appropriate password when authenticating. The format is simply:

<auth type="bluestem">

In addition to adding the <auth> tag in the configuration file you must also modify the action attribute of your form's <form> tag to change http to https and append -auth to cgiwrap:

<form name="myform" method="post" action="https://www.uic.edu/htbin/cgiwrap-auth/bin/formmail/FormMail/~adabyron/myform.sgml">

Important note: The submitter must already be authenticated via Bluestem prior to submitting the form. If they are not authenticated, Bluestem will be invoked but the form submission will not be transmitted to FormMail. This is because http posts cannot be redirected. To ensure that the submitter is authenticated, provide instructions at the top of the form and include an authentication link that will redirect back to the form after authentication:

https://www.uic.edu/htbin/location.pl?location=http://www.uic.edu/~adabyron/myform.html

<mail> tag

Each <mail>...</mail> tag set describes an email that will be sent when the form is submitted. More than one email can be generated (using different formats) and each email may be sent to multiple recipients. The format is:

<mail name="section_name" nomail if="if_cond"> </mail>

Attributes

The following attributes are optional for the <mail> tag:

  • name="mail_name" - Used to identify the mail section for debugging.
  • nomail​ - If used, no email from this section will be sent. Used for debugging. If you do not want any email sent when the form is submitted, you must have at least one set of <mail></mail> tags with the nomail attribute
  • vtype="validation_type" - type of validation
  • if="if_cond" - Email will be sent only when if_cond evaluates to true (nomail attribute will override this, if present).

Between <mail> tags, additional tags can be used to format the headers and body of the email:

  • <to>...</to> - Use one tag per email address. The default is NetID@uic.edu of the owner of the configuration file.
  • <cc>...</cc> - One tag per email address. No default.
  • <reply-to>....</reply-to> - Sets the Reply-To header. Specify the email address of the submitter, or perhaps your email address on emails sent to others. No default.
  • <from>....</from> - Sets the From header on mail. Normally best to leave alone, and rely on the Reply-To field. But if you have to set it, you can. Sometimes useful if the mail will be sent to an automatic program like listserv. The default value is web_mailer@uic.edu.
  • <subject>....</subject> - Sets the subject. Defaults to form_name submission, where form_name is the name of the form used in the configuration file.
  • <body>....</body> - Specify the body of the message. The default is a list of all filled in fields. 

If you specify multiple values where only one is allowed (for example <subject>) no error message will be generated, but only the last tag will be used. In addition, the email will automatically contain the following headers:

  • X-NetID: NetID where NetID is the NetID of the owner of the config file.
  • X-fm_form: form_name path where form_name is the name of the form from the config file, and path is the full path to the config file.

If there are no <mail> tags in the configuration file, or if all <mail> tags have if_cond attributes that evaluate to null, then a default email is generated, and sent to NetID@uic.edu address of the owner of the configuration file. But if all <mail> tags include the nomail attribute, then no email is generated. In other words, you have a very flexible ability to adjust who gets what email. If it seems that you wanted to generate an email, but for some reason all conditions evaluate to null, then a default email is sent just to be sure information is not lost. On the other hand, if it is clear you don't want any mail (by specifying nomail on all <mail> tags) then you don't get any.

Complete example

<!doctype form system 'FormMail-3.0.dtd'>
<form name="myform" contact="adabyron@uic.edu">
  <mail>
    <to>adabyron@uic.edu</to>
    <reply-to>$email_address</reply-to>
    <subject>Form Submission from $name</subject>
    <body>
      $name would like to be contacted at $phone_number or $email_address.
    </body>
  </mail>
</form>

<file> tag

Each <file> tag set formats content that will be saved to a file the form is submitted. You may write (or append to) more than one file (perhaps with different formats) if you have multiple <file> tag sets. The format is:

<file name="section_name" nofile if="if_cond"> </file>

​Attributes

The following attributes are optional for the <file> tag:

  • name="section_name" - Used to identify the file section for debugging.
  • nofile​ - If used, no information is saved to file. Used for debugging.
  • if="if_cond" - File will be written only if if_cond evaluates to true (nofile option will override, if present).
Between <file> tags, additional tags can be used:
  • <filename>...</filename> - One tag per file that you will append to. No default. Be sure this file is writable by the owner or group of the configuration file.
  • <dirname>...</dirname> - One tag per directory. No default. A new file (of random name) will be written to this directory upon form submission. Be sure this directory already exists and is writable by either the owner or Unix group of the configuration file.
  • <dirname filebase="prefix">...</dirname> - Filebase is an optional attribute, to specify the beginning part of the random filenames written to the directory.
  • <body>....</body> - Specify the text written to file. Defaults to the list of all filled in fields.
FormMail is oriented towards sending mail. If you want to write to disk and not send any mail at all, you still must include a <mail nomail></mail> section to block the sending of email. Also note that writing files is a bit more problematic than sending mail. Questions of permissions and disk quotas can cause problems. If the write does not happen, FormMail will try to notify the form submitter.
 
If one or more <file> sections are supposed to write files, and at least one of them succeeds in writing the file, no error is generated. But if all of them fail, then an error is shown to the form submitter. That means, if you have multiple sections for writing files, and something is wrong with one of them, the user will not see any error, since the info is saved to disk somewhere.

Complete example

<!doctype form system 'FormMail-3.0.dtd'>
<form name="myform" contact="adabyron@uic.edu">
  <file>
    <filename>form_submissions.csv</filename>
    <body>
       "$name","$phone_number","$email_address"

    </body>
  </file>
</form>

<response> tag

The <response></response> section controls the HTML generated in response to submitting the form. There may be many such sections, and they are evaluated in the order presented in the configuration file. The syntax is:

<response name="section_name" if="if_cond" url="url"> </response>

The sections are evaluated in order. If the first to evaluate to true contains a URL redirection, the output is redirected. Otherwise, all sections that evaluate to true are sent back to the client browser. The body of a <response> section should contain the HTML code enclosed in a <![CDATA[]]> tag:

<response name="html_response">
<![CDATA[
  <html>
    <head>
     <title> Submission complete </title>
    </head>
    <body>
      <p>
        <strong>Thank you</strong> for submitting the form.
      </p>
    </body>
  <html>
]]>
</response>   
If you choose to use the <response> tags to generate any part of the HTML response, you are entirely responsible for generating the whole response page, from the beginning <html> tag to the ending </html> tag. 

if_cond attribute

The optional if conditions specified in the <format>, <validate>, <mail> and <response> sections are expressions separated by boolean ANDs and ORs. But the conditions are not totally general, because parentheses are not allowed, and the ANDs bind tighter than the ORs. Therefore:

expression_1 AND expression_2 OR expression_3 OR expression_4 AND expression5
is parsed as:
(expression_1 AND expression_2) OR (expression_3) OR (expression_4 AND expression_5)
Each expression is evaluated as a string comparison or numeric comparison, depending on the operator used. Each expression should take one of the following forms. Note that each comparison operator must be delimited with blanks.
 
Expression Evaluates to true if Type
string string evaluates to non-null string
NOT string string evaluates to null string
string_1 eq string_2 string_1 equals string_2 string
string_1 ne string_2 string_1 does not equal string_2 string
string_1 pre string_2 string_1 begins with string_2 string
string_1 npre string_2 string_1 does not begin with string_2 string
num_1 == num_2 num_1 equals num_2 numeric
num_1 != num_2 num_1 does not equal num_2 numeric
num_1 >= num_2 num_1 is greater or equal to num_2 numeric
num_1 <= num_2 num_1 is less than or equal to num_2 numeric
num_1 > num_2 num_1 is greater than num_2 numeric
num_1 < num_2 num_1 is less than num_2 numeric
 
A string is either a hard-coded string (case-sensitive), or a dollar-variable, such as $var or $fm_name. The string should not contain internal blanks. For numeric comparisons, numeric should evaluate to a number, where null evaluates to 0. Using numeric comparisons with non-numeric strings is undefined, and should not be relied on to produce either true or false.
Last updated: 

September 21, 2016