eForm - The Electronic Form Snippet

Index

Who's responsible for eForm

Originally developed by Raymond Irving (15-Dec-2004)
Version 1.3 - 1.4 extended by: Jelle Jager (TobyL) September 2006

Captcha image support - thanks to Djamoer
Multi checkbox, radio, select support - thanks to Djamoer
Styles (for these docs) 'borrowed' from Adam Crownoble's QuickEdit

What is eForm?

eForm converts a web form into an email which can be sent via email to specified users. Its main features are: html form mail with attachments, auto-respond, report generation using placeholders and extended form validation.

What's New

Version 1.4.1

  • Fixed: inconsistent casing in event names. All events params are now in the form &eFormOn... (although the &eformOn... will still work)
  • Fixed: If subject comes from a form field the value is cleared before merging placeholders
  • Updated: Debug placeholder is now automatically added to form and thankyou template. (It is not auto-added to email message to avoid sending out sensitive info, although you can add the placeholder manually offcourse)
  • Fixed: Missing language file produces fatal error. (Will now generate a debug message if debug is on)
  • Fixed: Missing 'replyto' in AddAddressToMailer function.
  • Fixed: Erroneous closing slash (/) being added in <option ..>> tags
  • Fixed: No whitespace before 'selected' and 'checked' attributes
  • New: Extra event parameter &eformOnBeforeFormParse (triggered as soon as templates are loaded)
  • New: Extra event parameter &eFormOnFormValidate (triggered after eForm validation has occurred)
  • New: Extra event parameter &eFormOnBeforeFormMerge (triggered when and before form is displayed)
  • New: Extra event parameter &eFormOnBeforeFormParse (triggered after template(s) are loaded and before they are parsed)


You can see a more extensive version history here.

Installation

  • Unzip the zip file into the assets/snippet/ folder. You should now have an extra folder called eform.
  • Create a new snippet, name it eForm and copy and paste the content of the eform.snippet.tpl file
  • Start reading this file and the examples
  • Create forms

Snippet Parameters

eForm is very flexible and there's quite a collection of parameters you can use to get eForm to do what you want. Read some of the examples if you're unsure what to do.

Required parameters

Optional parameters

PHP Event Functions:

The eForm event functions are now incorporated into the parameters. They are:

Examples:

[!eForm? &to=`me@mydomain.com` &gotoid=`1` &tpl=`orders` &report=`orderreport` !]
[!eForm? &to=`sales@mysuppliers.com` &category=`Purchase Order` &tpl=`chunkPurchaseOrder` &report=`chunkPurchaseReport` !]

Placeholders

For all normal form fields eForm automatically inserts appropriate placeholders. However there are a few that you may need to add manually:

Datatypes and formatting

eForm is incorporating a form parser which extracts formatting and validation options from each form field. To set options for a field add the eform(pseudo) attribute to each required form field.

<input type="text" name="color" eform="A Color:string:1" />

The basic format of the eform attribute is:

[description/title]:[datatype]:[required]:[validation message]:[validation rule]

Data types

You only need to set the following data types. Others will be set automatically (radio & checkbox as they are, string for textbox and listbox for select)

Standard validation: All fields that are required will be checked if they are left empty.

  • string - No specific validation besides checking if it's empty if the field is required.
  • date - Checks if it is a valid date (based on php's strtotime() function)
  • integer - Checks if it is a number (does not check if it is in fact an integer)
  • float - Checks if it is a number
  • email - Checks if it's a valid email address using a simple regular expression
  • file - (for file upload input) - checks if a size error occurs, does not currently check file type
  • html - Same as string except that it converts line endings (\n) to <br /> tags

The listbox, checkbox and radio fields do normally not require the datatype to be set. eForm will recognize these automatically. It will validate the values against the list of values placed in the form.

Extended Server Validation

This version instroduces extended server validation and word filtering using very flexible validation rules that can be set in teh eformattribute. You can set 2 extra validation parameters, a custom error message and a validation or filter rule.

example: eform="Year of Birth:integer:1:Must be between 1950 and 2002:#RANGE 1950-2002"

The validation rules

  • #LIST - comma separated list of valid values
    example: #LIST blue,red,green.maroon
  • #RANGE - a comma separated list of numbers or numeric ranges. When setting a range the order is not important. 1~10 or 10~1 will both validate a number between 1 and 10 (inclusive). Handles negative as well as positive numbers
    example: #RANGE 1,3,-5~-15,60~82
  • #SELECT - list of valid values retrieved from a database query The query should only return a single column of values (the function only checks against the first returned column). You can use the {DBASE} {PREFIX}tags which will be replaced by the MODx database name and table prefix respectively.
    example: #SELECT keyword FROM {PREFIX}site_keywords
  • #EVAL - string of php code. Should return either true or false
    deprecatedAlthough #EVAL still works in eForm 1.4 this rule will very likely no longer be supported in future versions. Use #FUNCTION instead.
  • #FUNCTION - Name of a function. The function should expect one parameter (the posted value) and return either TRUE or FALSE. See the eform event example on how you can include a function. example: #FUNCTION myValidationFunction
  • #REGEX - regular expression - syntax as for preg_match() - see php manual
    example: #REGEX /^[a-z]+ [a-z0-9_]+/i
  • #FILTER - Filters do not validate the input but simply replace words or values using filter criteria. You can use the following filters:
    • #FILTER #LIST
      use double pipe to separate 2 comma separated lists of words and replacement values.
      example; #FILTER #LIST badword,verybadword||goodword,verygoodword
    • #FILTER #EVAL
      example: #FILTER #EVAL return myFilterFunction($value);
      (offcourse you have to make sure the function exists somehow)

      example filter function
      function myFilterFunction($value){
         $badWords = array('scribble','coding');
         $goodWords = array('design','sleep');
         return str_replace($badWords,$goodWords,$value);
      }
    • #FILTER #REGEX
      regular expression replace - syntax as for preg_replace() separate the search and replacement expression with a double pipe symbol (||)
      TODO: example

Select boxes, radio options and checkbox fields

Select boxes, radio options and checkbox fields now have working automatic validation. Any input for these fields is validated against the values set in your form template. This avoids anyone tampering with the form by adding their own values to these fields

Hidden fields

By default hidden fields are validated as a protection against tampering by comparing the input against the value set in the form template (much like the select, checkbox and radio fields) In some circumstances this may not be desirable however. For instance when you use some javascript in your form to store a result in a hidden field. In those cases you can turn this behaviour off by setting the eform attribute (with or without it's own validation).

Hidden field example 1.
The default behaviour is handy for instance if you are storing a document id and want to be sure no one can tamper with the id. the field would look like this:
<input type="hidden" name="docId" value="31" />

Hidden field example 2.
Suppose you have a form where a javascript calculated value is stored in a hidden field. To avoid the hidden field being validated at all you add the following eform attribute: <input type="hidden" name="calculatedField" value="" eform="::0::" />

Hidden field example 3.
Same scenario as 2 but suppose you want to make sure a value is returned and that it stays within a certain range. The eform attribute is set with: title,integer data type, required field, error message and validation with #RANGE (in this example a value between 1-10) <input type="hidden" name="calculatedField" value="" eform="Calculated Value:integer:1:Calculation out of range:#RANGE 1-10" />

Form field examples with validation

1. Selectbox - set as required field (no validation required)

<select name="mySelect" eform_options="Select Country::1" /> (datatype left blank)
<option value="en-au">Australia</option>
<option value="en-us">USA</option>
</select>

2. Textbox - required and format set to date

<input type="text" name="dobDate" eform_options="Date of Birth:date:1:@EVAL return (strtotime($value)!==-1)?true:false;" />

3. Multiple checkbox - required, eform_options only set once.

<input type="checkbox" name="myColors[]" value="Red" eform_options="Colors::1" /> (datatype left blank)
<input type="checkbox" name="myColors[]" value="Green" /> (datatype left blank)

Todo