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.

Flat File Data
This field contains the 'free-form' data to write to the flat file destination. You can place any type of text you want in this area, including all tags received by toggling on HTML WYSIWYG mode. This field support dynamic variables, which means you can use tokens to represent PHP or field variables.

Placing any value in the field will over-ride the values set in the Flat File Simple List text area. That is, the Flat File module can work in free-form mode, or can create Excel compatible lists.

Another way of saying it: If you place values in this area, it's probably because you are creating unique files for each instance of the form being filled out. If you use the Flat File Simple List, you're probably trying to create an Excel spreadsheet where many entries are stored in one file.

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, FormBoss 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 field Name/Value token.

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

To process this field in our condition statement we need to append the proper index of the field used for checking the condition using PHP array index format. It may sound confusing, but it's quite simple when you see it:

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

In short, the non-array way would be to simply use:

#{email_condition} == 'Recipient A'

But because we need to check an array index (again, because PHP treats checkbox items as arrays), we simply add the [0] part before the closing brace (}).

How do we know which array index to use (the number part)? In our example the checkbox field has two values; array indexs start with 0, so the first field, Recipient A, is [0], where Recipient B would be [1].

This numbering simply climbs up by 1 for every checkbox item you add.

File Location & Name
This is the name and where the flat file will be saved to, relative the job folder. Thus, if you place ../filetest.txt, the file will be saved one directory up from the job folder with the name of filetest.txt.

It's important to understand this field should be thought of as a series of pieces which when combined form a complete path, filename, and extension.

By default we save to the some directory as the form. Thus, if we used:

file.txt

Our file would be called file.txt in the same location as the form.

Of course the problem with this is should a second entry arrive, the first file would be over-written.

Thus, we generally need to use Dynamic tokens when creating file names. To help us create such unique names we can use several tokens in the File Location & Name field:

${session_id} = session_id();
${timestamp} = time();
${datetime} = date('Y-m-d H:i:s', time());
${remote_ip} = $_SERVER['REMOTE_ADDR'];

This field is also dynamic token ready, which means we can use #{field_name} and ${php_var_name} to create a dynamic file name based on form field entry values.

Thus, when we put this all together we can string a series of tokens and characters together such as:

#{last_name}-${remote_ip}-${timestamp}.txt

To create a file name like:

Smith-127.0.0.1-1297196254.txt

As of Build 699 this field now accepts the standard FormBoss 2 token set, which means we use F{} for field elements, P{} and G{} for POST and GET, and S{} and ${} for SESSION and raw PHP variables.

Thus, we could rewrite the sample above to be:

F{last_name}-${remote_ip}-${timestamp}.txt

SECURITY ALERT! Use caution however, in that you generally do not want to give your sites visitors access to your servers file system without some form of filtering. At very minimum you should verify the integrity of the field variable first by passing the value to a PHP variable in the PHP Top Code block, and use that filtered value to process the file name and path (if applicable).

The reason why is that when it comes to naming files there are a few openings for malicious activity to occur.

The first is in the path the file is saved to. By placing a ../ in the dynamic field the visitor will effectively save the file one level up from the base location, provided the web server has access to that location.

The good news is on that front, that is, file location, as of build 699 our ability to secure the file system has been simplified with the Remove Path Data From Dynamic Location option.

However, we still have the issue of file extension. A user could add a .txt or .img to a form field value, and if you don't provide your own extension, there's will be used instead. This isn't so much a security risk as path location, but it's still important to force your hand by always providing your own file extension if possible.

FInally, as mentioned above, if you want to use the ${php_var_name} token, the code for defining the PHP variable must be placed in the PHP Top Code text area.

Remove Path Data From Dynamic Location
New to Build 699, this option works in conjunction with the dynamic variable ability of the File Name & Location property. It works by removing any path data from dyanmic field variables.

Although we warn to be careful with this setting in the editor, careful modification of the path by sanitizing it first in the PHP Top Code block will go a long way to making sure users do not accidentally or maliciously hard our system. If in doubt, do not check this box however!

Create Path If It Doesn't Already Exist.
New to Build 701, this setting allows us to dynamically create the path to the upload location. This setting works independent of the Remove Path Data From Dynamic Location settings, as we often do want to create a path dynamically without being bothered to do so manually.

As with Remove Path Data From Dynamic Location, this setting is fraught with danger. Unless you know exactly what your doing and/or can absolutely 100% trust your users, use a database powered file management solution instead!

Field Separator
When creating files you may wish to have each field separated by a delimiter of some sort. This is essential for creating Excel files. This field allows you to set the field separator to match the requirements of the format you want to create. The default is \t, which is tab separated.

This field is only used for Flat File Simple Lists.

New line Character
This is the character that will terminate each line of text. Generally speaking the default should work, though in some instances you may wish to experiment with \n.

This field is only used for Flat File Simple Lists.

Flat File Simple List
The Flat File module works in one of two ways: Either you create a custom file using the Flat File Data text area, or you can create a Excel like list using this field. If you choose Flat File Simple List, FormBoss will take the field and PHP variables you set in this text area and use the Field Separator and New line Character fields to create the file for you. This is most useful in situations where you need to create Excel compatible files where each entry is tab delimited, and on its own line.

Write Flags
When writing to your flat file you can set the type of write operation to use with the values in this text area. The Default set will append data to the end of the file and lock the file while doing so. This is your best bet for most operations.