How to use the {emailform} tag

Dictator includes a built-in secure form processor that is activated via the emailform tag. This feature is primarily intended for inclusion by web developers.

To make use of the emailform tag, you first must place the HTML form you want to use in Dictator’s forms directory. This form file must have an “.html” file extension. Dictator comes with an example contact.html form file that you may want to look at as an example.

Dictator currently can process text, textarea, select, and radio button form fields. For each form field’s “name” attribute, use the following format:

name_required_123

The first part (name) is your usual HTML form field variable name. The second part “_required” is optional and should only be included if this particular field is required to complete the form. The last part is the maximum length of this field. You may also omit this, but use of it is recommended for security. For instance, if you are asking for someone’s telephone number, you may want to limit it to 20 characters to prevent abuse. Note that this is different from the HTML “maxlength” attribute as it communicates to Dictator only, whereas the “maxlength” attribute communicates to the client’s browser. Here is an example:

<input type="text" name="telephone_required_20" maxlength="20" />

If you are a security-minded web developer, you may think to yourself that specifying these items (required and maximum length) in this manner opens these fields to manipulation by hackers. This is not the case because Dictator reads this information directly from the HTML form source file (in your forms folder), not from the form the user posts. Dictator verifies that the form the user is posting matches the one stored on your file system. If the user is trying to manipulate variables they will be ignored.

Once you have created your form and placed it in Dictator’s forms directory, you may then refer to it from within Dictator admin by using the {emailform} tag. Below is the proper usage of this tag:

{emailform:formfile.html|email address|message subject|thank you message}

For example:

{emailform:contact.html|you@yourdomain.com|User submitted form|Thank you, your message has been sent!}

Unlike other Dictator tags, each attribute in the email form tag is separated by a pipe “|”. These attributes are summarized below:

Form file name that you want to load (must end with .html)
Email address(s) that you want the form to send to. If specifying multiple addresses, each must be separated by a comma.
The subject of the message that you (the recipient) will receive when a user completes the form
The message to report to the user when they have completed the form successfully. If this attribute is omitted, then a default “thank you” message will be sent.

In this manner, you may reuse email form tags to send to different addresses throughout your site, even if they are using the same form file.

Security Issues

Because forms are one of the primary security issues with any web site, Dictator includes several security measures for handling forms.

As indicated earlier, Dicator confirms that the form the user is submitted matches exactly the one specified on your local file system for all variable names, lengths, and required status.
If you specify that a form field should be less than 255 characters long (maximum length) then Dictator will not allow any line feeds, carriage returns, or null characters within the posted data.
If a user attempts email header injection, Dictator will not process the form. Furthermore, it will prevent the user from submitting additional forms for a period of 24 hours by tracking their IP address.
Each form may only be submitted once and it may not be successfully submitted from anywhere other than your Dictator-powered site. Dictator tracks each form submission to a specific form request preventing arbitrary submission of forms.
You may optionally use CAPTCHA images to prevent the form from being potentially submitted by non-humans. Details forthcoming.