Deriving Fields in FormMail

Starting with version 2.00, FormMail supports the concept of deriving fields from other fields.

Here are some issues that derived fields solve:

• you want to ask people for their First Name and their Last Name separately, but FormMail insists on having a "realname" field (a single field containing the whole name);
• you want to store the date and time of the form submission, along with the data, in a CSV file, but you don't want to rely on JavaScript in the form;
• you want to include the date and time of the form submission in the email that you get sent;
• you want your own field name for a person's email address - you don't want to be stuck with "email", which FormMail requires.

To derive a field, you simply add a hidden field specification in your form, like this:

<input type="hidden" name="derive_fields" value="specification" />

The specification part is a comma-separated list of field derivations.

A field derivation looks like this:

DerivedField = Value1 joiner Value2 joiner Value3...

A Simple Field Derivation

Here's an example of a simple field derivation. It allows you to call your field "EmailAddress", and also provide the special "email" field to FormMail:

email = EmailAddress

The complete entry in your form would be:

<input type="hidden" name="derive_fields" value="email = EmailAddress" />

This says to FormMail: create a new field called email and give it the same value as the field EmailAddress in the form submission.

And somewhere in your form you would have this field:

<input type="text" name="EmailAddress" />

Joining Two Fields to Create a Third

FormMail uses the special field "realname" to tell you who the form submission is from. But suppose you want to ask people their first and last name separately - in two fields.

To solve this, you can derive "realname" from the two separate name fields:

realname = FirstName + LastName

The "+" is a joiner. It tells FormMail to join the values of the fields FirstName and LastName together with a single space between them. The "+" joiner is intelligent; it won't add the space if the following field is empty.

For example, suppose I enter my name "Russell" into your FirstName field, but I don't enter anything into LastName. The "+" joiner will create a realname field that contains "Russell" - no extra space added to it.

There are several joiners available:

So, to derive the two fields email and realname, your form field entry would be:

<input type="hidden" name="derive_fields"
    value="email = EmailAddress, realname = FirstName + LastName" />

Special Values

FormMail can insert a date or time value when you're deriving a field.

Date = %date%

will create a field called Date, containing the current date on the server in this format:

DD-MMM-YYYY

Similarly for time:

TheTime = %time%

will create a field called TheTime, containing the current time on the server in this format:

You can also specifiy parts of dates and times - see below for more information.

Literals

When deriving a new field, you can use existing fields and also literal values.

A literal value is any string surrounded by '%' and single quotes:

%'This is a literal value'%

For example, suppose you wanted a new field which showed the date and time with a prompt:

DateTime = %'Date of form submission was: '% . %date% + %time%

The field DateTime will look like this:

Date of form submission was: 13-May-2004 22:54:06

To get a single quote literal, use this:

%'''%

Date and Time Components

The following shows the special values you can use to get various components of the date and time:

A Complex Specification

Here is a sample derived fields specification which is somewhat complex:

<input type="hidden" name="derive_fields" value="email = EmailAddress,
    Date=%dom0%.%'-'%.%moy0%.%'-'%.%year%,
    Time=%time%" />

This will create:

• a field called Date which looks like this: 04-09-11 (on the 4th September, 2011)
• a field called Time which looks like this: 09:15:00 (at quarter past nine in the morning)
• a field called email which is a copy of the field called EmailAddress

File Uploads

From version 7.06 of FormMail, if you use a file upload field name in a derivation, the name of the file on the user's computer is substituted.

For example, supposed you have a file upload field called "your_picture" and the user uploads a file called "photo.jpg" from their computer with this field. The following derivation will create a field called "photo_id" with the value "15-6-2006photo.jpg":

<input type="hidden" name="derive_fields" value="photo_id=%date%.your_picture" />

You can also derive a field containing the size of the uploaded file. See Other Functions below.

Conditional Derivation

From version 7.07 of FormMail, you can derive a field based on a simple conditional test. The syntax is:

%if(field_name;then-spec;else-spec)%

If the given field is empty, then the else-spec is used, otherwise the then-spec is used to derive the field.

Here's an example which creates a message field depending on whether a file was uploaded:

<input type="hidden" name="derive_fields"
    value="upload_mesg=%if(your_picture;%'Picture was uploaded'%;%'No picture was uploaded'%)%" />

Obtaining Server Values

You can create a derived field using the special names of Server Variables. Note: this feature is only available in FormMail version 5.02 or later.

Server Variables are provided by PHP and often contain useful information. A common use is to obtain the user's IP address or browser type.

All the available Server Variables are defined here: www.php.net/reserved.variables, under the heading $_SERVER.

You can also obtain Environment variables this way, but their availability is not well defined, except for the CGI interface.

The following example shows how to obtain the user's IP address, browser type, and the referring page:

<input type="hidden" name="derive_fields" value="ipaddr = REMOTE_ADDR,
   browser = HTTP_USER_AGENT, referrer = HTTP_REFERER" />

Use in CSV Files

As you probably already know, FormMail supports the creation of CSV files. If you want to put your derived fields in your CSV file (a common use of dates and times), just refer to the field you've created.

Here's an example:

<input type="hidden" name="csvcolumns" value="firstname,lastname,email,Date,Time" />

(where Date and Time are derived fields, like in the previous section).

Special Characters

As at version 2.09 of FormMail, you can insert any ASCII value into a field. You do this by using the character's hexadecimal value.

The syntax is simple:

%XX%

where XX is the hexadecimal value (in upper case).

Below we've shown several special characters together with the %XX% value you need to use:

The following (rather complicated-looking) example joins some text and special characters together to create a field called HexTest.

<input type="hidden" name="derive_fields"
    value="HexTest = %'comma:'%.%2C%.%' quote:'%.%27%.%' plus:'%.
    %2B%.%' dot:'%.%2E%.%' asterisk:'%.%2A%.%' percent:'%.%25%" />

This example creates a date field with '.' separating the numbers:

<input type="hidden" name="derive_fields" value="Date = %dom0%.%2E%.%moy0%.%2E%.%fullyear%" />

Other Functions

Beginning with version 7.12 of FormMail, derive_fields supports a number of useful functions for extracting or modifying the values of fields. These functions are described below.

<input type="hidden" name="derive_fields" value="
    your_picture_size=%size(your_picture)%" />

<input type="hidden" name="derive_fields" value="
    image_type=%ext(your_picture)%" />

<input type="hidden" name="derive_fields" value="
    realname=%ucase(full_name)%,email=%lcase(emailaddr)%" />

<input type="hidden" name="derive_fields" value="
    realname=%trim(full_name)%, comments=%ltrim(comments)%" />

<input type="hidden" name="derive_fields" value="
      num_persons=%ltrim0(num_persons)%" />

nextnum(pad;base)

<input type="hidden" name="derive_fields" value="
      order_num=%nextnum%,
      file_num=%nextnum(6)%,
      secret_code=%nextnum(8,16)%" />

Using Functions with Conditional Derivation

Due to size requirements, there are limits to the amount of parsing FormMail can perform on derive_fields. So, in order to use the special functions or multiple conditionals, you must perform your complex derivations in stages.

For example, suppose you want to include the size of an uploaded file in a message field you need to create. Using the earlier Conditional Derivation example, you could change this:

<input type="hidden" name="derive_fields" value="
    upload_mesg=%if(your_picture;%'Picture was uploaded'%;%'No picture was uploaded'%)%" />

to this:

<input type="hidden" name="derive_fields" value="
    upload_size=%size(your_picture)%,
    upload_mesg=%if(your_picture;%'Picture was uploaded with size '%.
    upload_size;%'No picture was uploaded'%)%" />

Limitations

Languages other than English may not be supported with the date-time Day name and Month name expansions. Feedback on this would be appreciated, and we may be able to resolve any issues in a future version.

Enjoy!