Basic Attributes

Design Notes
These are notes you can input that help you and other production staff understand your confirmation elements logic and purpose. This text is never used in the live form in any way, it is only for internal development.

Email Message

This field works by wrapping the field id's of your form elements or names of PHP variables in tokens and returning the run-time value of that variable exactly where you've placed it in the content body of your email message. It is important to make note that although the general procedure is the same, the token syntax for form elements and PHP variables is slightly different. We'll look at each in turn.

Form Elements
You can retrieve the runtime values of your form elements using the format:

#{field_name}

That is, for every form field element you have, it has a property of Name/Value. This Name/Value property is what identifies itself as a unique item in RackForms, which means if you include the Name/Value in a token within the email message body, the runtime value of that field element is returned in place of the token.

An easy way to see how this works is to click on the Dynamic Variable Picker link directly below the Email Message text area. When you do so, a new window appears that automatically creates a valid list of field items. When you click on a field item Name/Value, that element is added to your Email Message.

Let's take the example of an event calendar submission form. Your users will be filling out names, dates, places, and so. The final destination for the event listing will be both web site and printed publication. In most cases this information should have a standard format, using the Email+ module lets you manipulate the field items into the format each requires. You could thus create the final event listing within RackForms, so that when it comes time to transfer the event listing to the printed publication and web site*, you only need to copy/paste the text from the Email+ email message.

* It should be pointed out this is the exact same principal the SQL+ module uses.

The other obvious advantage of this field is the ability to create HTML formatted messages.

By default, the HTML edit function is disabled. Click the Toggle HTML WYSIWYG button to enable it. Once in HTML mode, create the message as you see fit, remembering the limitations of email formatting, such as image blocking in email clients and style limitations.

Of course when in full HTML mode you still have access to your dynamic variables, again, in the form of #{field_id}. Sprinkle these dynamic variables around the HTML email message in any form you see fit.

PHP Variables
We can retrieve the runtime values of local PHP variables using the format:

${php_variable_name}

You'll notice the syntax is almost identical to that of the Form Elements, only we use a dollar sign ($) and then the braces.

For example, let's say I create a PHP variable like so and place it into the Page PHP Top Code text box:

<?php
$text1 = 'tester text 1';
?>

To retrieve this variable at runtime, I would use the following text in my Email Message text box:

[...]dynamic PHP var: ${text1}

Notice we do not use a dollar sign in the variable name e.g., we use ${text1} not ${$text1}

One final point is that we only have access to local PHP variables, in that we cannot list a variable that has been used a previous page, nor can we use $_SESSION variables. The only valid variables are those we define on the same page as our Email+ module is running.

Combined with dynamic variables, RackForms Email Plus gives you extraordinary flexibility.

Processing Buckets
RackForms allows us to place a special token in our email message block called BUCKET. This token will take the bucket in question and display any repeated rows in the email body. It's very important to note this only shows repeated items, not the first items in the first or original bucket. To show those items we use the standard F{} token we would for any other form field item.

Confirmation/Query Condition

Confirmation Condition PHP Code

This field allows you to specify a condition which must be met for the confirmation field to be processed.

We can create code manually, or use the Condition Wizard.

Condition Wizard

If you're new to using conditions, or simply want to have RackForms generate the condition code for you, the wizard is a fast and easy way to do so. To create a confirmation condition, simply follow the wizard from top to bottom.

Start by mousing over the This Field: select item. All fields in your form will display, select the item you want to base the condition on.

Please note if we select a Checkbox field an additional select item will display, Having This Checkbox Value (optional):. This select item will display all possible values for that checkbox. Select which value you want to base the condition on. When you do, the condition process is complete.

For all other fields, the next step is to set the Must: field. This will take the value of Equal or Not Equal, and several others.

Finally, type into the This Value: box to set which value the form field we selected above will validate against.

If you want to add additional conditions, such as a name must be Equal to Steve and age less than 10, first select the Additional Condition button and start from the top of the wizard again.

Hand Coding Conditional Code

The logic takes the form of:

Variable 1 | Condition | Variable 2

For example, let's assume we have a radio item in our form with the Name/Value of opt_1. The radio item has two possible vales, 'Yes' and 'No'. If the value of opt_1 is 'Yes' we want to send an email, if no, we do not.

We would write the Confirmation Condition PHP Code as such:

#{opt_1} == 'Yes'

In other words, we use the token for our field variable like we would in other property boxes, that is, a pound sign (#) followed by the Name/Value of the field in braces. Recall that at run time this token evaluates to the value set by our forms users, which in this case will be the value of the radio button with the Name/Value of opt_1.

We then set the comparison, in this case out comparison is equal too, denoted with the double == sign. Finally, because we know our radio item is a string value that can be 'Yes' or 'No', we wrap the value we want to check for in single tick marks.

On the raw code side, RackForms wraps the token call in an isset() block, which is further wrapped in the proper PHP if() syntax:

if(isset($_SESSION['qs']["{$_SESSION['entry_key']}"]['opt_1']) && $_SESSION['qs']["{$_SESSION['entry_key']}"]['opt_1'] == 'Yes') { // condition code start

When run, if the users set value for the radio box was 'Yes', we would process this confirmation element.

Using Array Based Form Elements (Checkboxes)
PHP Treats checkbox items a little differently than other elements. The good news is the only element that needs this special attention is a checkbox field. The difference then, is that in order to use checkbox items we need to place an index indicator just after the form field name.

For example, lets say we have a checkbox field with the Name/Value: email_condition, and it has two elements: Recipient A and Recipient B

To process this field in our condition statement we append the proper index in the format of [index-number]. It's quite simple when you see it in practice:

#{email_condition[0]} == 'Recipient A'

#{email_condition[1]} == 'Recipient B'

Please note the [0] and [1]. These are the index positions of the field being checked. Compare this to a standard field token:

#{email_condition} == 'Recipient A'

A checkbox group has several items, the [0] and [1] bit tell RackForms which number item to grab.

How do we know which number to use? In our example the checkbox field has two values, and array indexs start with 0. Thus, the first field, Recipient A, is [0], and Recipient B is [1].

The rule then is our numbering simply adds 1 for every checkbox item in the group, and always starts at 0.

Email Delivery

To: email recipient(s)
In most circumstances you'll simply input a comma delimited list of email addresses. RackForms will then email a copy of the Form's elements in name=value format.

You can however, get more involved by using dynamic variables, those form values as identified by the id attributes of form element(s) previously defined on form pages.

For example, you could have a text field with an id of user_name. To include the user defined value of this field in your email, wrap the field 'id' in the stndard RackForms token format like so:

#{user_name}

Now at runtime RackForms will parse the submitted value of this field element and include it in the list of email recipients.

For best results, it is recommended to include all dynamic variables first, then any hard-coded email address as in:

#{user_name}, sample@yahoo.com

Notice the use of the space between the dynamic variable and the hard-code email. This is not strictly needed, but it does make reading a list of addresses easier.

Note: One requirement you must meet is each dynamic variable must be separated by a space.

New to Build 705, we can now use the handy Email Address Quick Select feature to quickly add saved email address to our To: field. This feature also allows us, as you would expect, to add and remove email address items at will.

SMS Carrier List

New to Build 694, this shortcut field allows us to easily select the most popular email addresses for sending SMS text messages. This allows you to send alerts to your mobile device the same as if you typed a text message directly on your phone.

It is important to note that unlike sending text messages from your phone, RackForms will by default want to send HTML based messages. For smart phones like Android and the iPhone that have build in HTML capabilities this should be fine. For most other phones however, your message will not be viewable, as these devices do not support HTML content. Thus, as the note below this field suggests, you'll want to click the Send as Plain Text (located below this field), as that way RackForms will only send plain text messages, which are guaranteed to be viewable by any mobile device.

From

Best supplied as an email address, however, this can be regular text. However, some servers, particularly shared hosting accounts or improperly configured dedicated servers, will need to have an email address only, as if not, the server will automatically append the servers name and domain to any value you input here.

The best method to determine your servers configuration is to simply create a sample form using email and see what happens when you leave the From: field blank. If you do get a domain name and server, contact your web host and ask them how and if you can edit the php.ini file to set a default From: address. The php.ini line looks like:

sendmail_from = me@example.com

This field is dynamic, which means you can assign any field that is not an array to process at form submission time as the emails 'from' property. Each dynamic element needs to be in token form, that is, #{token}, where 'token' in the Name/Value attribute of a form element.

From Name
As of Build 705 we can now use 'pretty' display names for the From Name: field. That is, normally when an email is sent we would just supply an email address to the From: field. Now we can specify a display name for the email as well.

This will show up in the email program's From: field as John Smith instead of jsmith@yahoo.com.

Care should be used when specifying a display name however, as a common spam technique is to use a 'fake' From Name: value.

Subject

The subject line of your email message.

Cc

A list of recipients to Carbon Copy this message on.

Bcc

A list of recipients to Blind Carbon Copy this message on.

Please be aware that due to possible limitations in the PHP mail() command, your Bcc recipients might need to be on different domains. Thus, Bcc's to user1@host.com and user2@host.com may not work as expected. Please be sure to test out the form before deploying in a production setting.

Reply To

This field allows is to set the reply-to property of the email such that when the email is sent, when we click the receivers email client reply button this is the address the email will be set as the send to address.

Email Label/Value | Item Separator

This option has two different meanings depending on what context you use it in. In the case of Simple Email submissions, the content is exactly as described below. However, if you are using the Email+ module, the usage is slightly different. Please see the Email+ module documentation for more information.

RackForms sends the values of your Simple Email as:

{field label} : {value}

To ease in reading form submissions, by default, RackForms uses a colon : sign to delimit the {field label} and {value}

For example, a field in RackForms that has the label:

Your Name

Entered with 'Matthew' by a user, would like this when sent in an email:

Your Name : Matthew

If you want a different delimiter such as a (pipe |)  (dash -) or any other character(s) include spaces, enter them in this box.

Format Email To Work Best With:

This option is mainly to provide a workaround for Microsoft Outlooks use of its Word HTML rendering engine. When set to Outlook mode we thusly use TABLE elements to present results, whereas Everything Else mode uses liquid DIV's and CSS 3. This is the mode best suited for Mobile devices in particular.

Simple Email Table (Simple Email Only)

Instead of a simple name value pair, you can have have RackForms create an HTML table that makes reading and manipulating from submissions easier. Please be aware, this checkbox only has an effect with the Simple Email module. This option is selected by default.

Although not widely used now, the table is styled with a CSS 3 nth-child selector, meaning when Email clients finally catch up, alternating rows will have a different color for easier reading.

Send as Plain Text
This option allows you to set whether or not your email message is sent as plain text or HTML. If you do check this box, you should be aware of how the various email settings effect the final output. At very minimum, we'll usually want to check this box when sending SMS messages, as most phones do not support HTML based text messages.

Let's assume we have two fields, Text 1 and Text 2, that hold the values: Value 1 and Value 2. The first two scenarios are when we have the checkbox checked, the second are unchecked (and thus, HTML email).

Scenario 1 - Plain Text With No Simple Email Table
Your email will be sent with each field separated with the the Email Label/Value | Item Separator you choose with each line \r\n terminated as:

Text 1 : Value 1
Text 2 : Value 2
          

Scenario 2 - Plain Text With Simple Email Table
In this case RackForms will create a "mock" table using \t\t and \r\n elements as:

Text 1		Value 1
Text 2		Value 2
          

Please notice the extra space between each element (the double tab: \t\t), and the fact that we do not use the separator anymore.

Scenario 3 - HTML With No Simple Email Table
In this case RackForms will create your email with HTML formatting applied. Using the same example input from above, the code created and sent would be:

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Test plain text Simple Email</title>
</head>
<body>
Text 1 : Value 1<br />
Text 2 : Value 2<br />
</body>
</html>

Scenario 4 - HTML With Simple Email Table
In this final scenario we will create HTML code that also uses a CSS3 based alternating row colors. The code created would be:

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Test plain text Simple Email</title>
<style type="text/css">
tr:nth-child(even) {
background-color:#efefef;
}
.name { font-family:"Arial Black", Gadget, sans-serif }
.value { font-family:Arial, Helvetica, sans-serif }
</style>
</head>
<body>
<table width="100%" border="0" cellpadding="3">
  <tr>
    <td valign="top" class="name">Text 1</td>
    <td valign="top" class="value">Value 1</td>
  <tr>
    <td valign="top" class="name">Text 2</td>
    <td valign="top" class="value">Value 2</td>
</table>
</body>
</html>

Interestingly enough, the only email client at the time of this writing to support CSS3 was the Mac Version of Office 2007's Entourage. That said, ass CSS3 gains acceptance more clients will offer native support.

Ignore (Skip) Empty Items (Simple Email Only)

This option tells RackForms to skip any item in Simple Email that has been left empty by the user. This can be very handy for large forms that may have similarly large number of option fields.

Email Priority

Some Email Clients allow you to set the urgency of the email message, RackForms supports the full Microsoft Exchange Server set with 'Highest' through 'Lowest'. Normal is selected by default, keeping this setting means email sent through FromBoss will show up without any priority coding.

Mark As To Do?

Some Email Clients allow messages to be tagged with 'to do' status, in the case of Exchange, this means a small red flag appears next to the message. Check this box to send RackForms email with this setting enabled.

Include user originated file attachments?

A powerful feature, checking this box means any File Upload elements that have the Save For Email Attachment / Flat File Data? checkbox checked will be sent as attachment components to your email message. This option works with HTML and plain text messages.

A common use of this would be classified ad placement for a newspaper web site, contest entry forms where users supply an image, or any other use where an email+file combination is desired.

Please note again: you must check the Save For Email Attachment / Flat File Data? checkbox and any file upload item you want included with the email message!

Include Digital Signature File Attachments?

Checking this option tells RackForms to include any Digital Signature Images created in the form as file attachments. This option is disable (unchecked) by default, as more likely than not such an attachment will have a very specific purpose not suited for most email delivery.

Include PDF File Attachments?

This checkbox tells RackForms that any pages we've defined with the Page PDF Output Properties > PDF Output Mode set as: Save For Email Output will be attached to the email being sent.

Static Attachment Name

This item, along with Static Attachment Path, lets us attach items to the email that are not user-originated, that is, files that come from the web server. This field sets a custom name for this item, essentially overriding the default behavior of just using the normal file name.

Please note that if no value is placed in this box then the file name as defined by it's path is used.

Static Attachment Path

This item defines the full path of an item we wish to attach to our email message. This path can be absolute:

C:\Users\Matt\Desktop\rackforms-features.txt

Or relative:

../rackforms-features.txt

The key of course is the path must be valid!

If the path is valid then that file, when the form is submitted, will be attached along with any user-defined items. This feature is thus very useful if we wish to provide our form users with a default file of some sort, such as a thank you package, 'next steps' message, and so on.

We can also pass a directory name here, and if so, all files within that directory, save for dot files, will be attached to the email. Use caution with this setting, in particular when using dynamic values.

Delete Static Attachment File After Sending?

When checked, any single files we've defined in the static attachment list will be removed after sending. For securities sake, this is not applicable to folders, only individual files.

Email Character Set

This field sets the character set of the email, both in terms of HTML charset declarations, and in the actual email body proper.

In most cases the default of UTF-8 will suffice, however, some European users may find one of the ISO methods will produce better results. Please consult the Wikipedia Entry on Character Encoding for more.

Email Encoding

In most cases the default of 8bit will suffice, however, when using standard PHP mail() with HTML messages, we may need to switch this quoted-printable, as sometimes letters will go missing form the email message, or new ones added.

Encode Carriage Returns as HTML?

This feature lets us encode line breaks and carriage returns as <br/> tags, which is useful if we want to keep a users original formatting. This feature is now enabled by default, though any jobs from older builds will need to have their email fields activated at least once for this setting to be used.

Additional Email Headers

Use this box to fill in any additional email headers your email client or CRM might require for security or other purposes. As a general rule, we do not want to use quotes (") in this box. Also, if adding more than one custom header, be sure to separate each with a comma!

Show Email Debug Info? (Formerly known as: Show SMTP Debug Info)

Check this box to show detailed Email/SMTP debug messages, which can help when setting up a relay for the first time, or with general email delivery messages.

Email Note:

All email from RackForms is HTML formatted Unless The Send as Plain Text Checkbox is Checked.

Email SMTP

You can use SMTP to send email. There are two three reasons why you would want to use this type of delivery:

1 - Security. SMTP allows SSL or TSL.

2 - Your web hosting provider, be it paid or in-house, doesn't allow the standard PHP email mechanism (mail()) to be used. Most of the time this is for security reasons.

3 - You're on personal computer and want to send test emails in a development environment. Windows and several other OS's aren't configured to send email by themselves, so unless you have a SMTP client of some sort installed or access to an Exchange Server, POSTFIX or so on, you cannot send php mail() on your local machine. Thus, we can use RackForms SMTP to relay mail to your web hosting provider, bypassing the no email client (MTA) problem.

Use SMTP Delivery

Unless this box is checked, RackForms will attempt to use the standard mail() command. Checking this box means all mail will be handled via the SMTP module, which means in order for mail to work you will need to configure the additional settings outlined below.

SMTP Server Address (server:port)

The contents of this field will depend on whether your SMTP relay uses authentication or not. If they do (as is the case with Google's Gmail), you will need to supply a domain name and postfix it will a port number, separated by a colon. For example Gmail would use:

smtp.gmail.com:465

If your web hosting provider allows for SMTP relay (they almost always do), your IP address which is dolled out by your provider will act as the authentication mechanism, and thus you may not need to use a secure port, and you can instead use:

smtp.your_host.net

Important: A port number will almost always be required when using SMTP delivery, so please be sure to check your email providers documentation for the proper value to use.

SMTP Username

If so required, this is the user name of your SMTP user account. On Google, this is your email address.

SMTP Password

The password of your SMTP relay.

SMTP Transfer Mode

Select from None, SSL, or TSL. For web service provider SMTP relay's you can generally leave this set to None. For Google Gmail, you would select SSL. Many corporate environments will use TSL.

Important Gmail SMPT Considerations

By default, Gmail may block attempts to use your account on remote web servers, and in particular, RackForms Cloud Hosting. If mail is not being sent, first log in to your Google account and check your security settings. If an account sign in was blocked you'll find a handy notification to that effect, complete with location of the login attempt and other details. If the server IP in the blocked list originated on your server, you can safely click the "That Was Me" button.

For RackForms Cloud Hosting users, you'll almost always find an entry for the following IPv6 or IPv4 address:

IPv6: 2600:3c00::f03c:91ff:fe67:7736
IPv4: 45.33.2.105

This is the RackForms cloud Hosting server IP address, so you can safely click the "That Was Me" button to allow access. Access from any other IP address is not from RackForms Cloud Hosting.

SSL Certificate Verification

This option controls how encrypted email methods are verified. The default is to verify SSL certificates, which means when using SSL or TLS, PHP first checks the servers certificate and makes sure it matches the servers domain name. If it doesn't the email fails. For most productions servers this should not be an issue, though it may require some setup, which you can read about here and here.

Alternatively, you may wish to send test emails on a local server that doesn't have an SSL certificate installed. If this is the case we can set this option to No, which means ignore any certificate issues.