Documentation | Flat File

RackForms v7.8.8

flat file

Latest Release: Build 958 - Arpil 18th, 2023

Home > Confirmation Elements > Flat File

Flat File

In Brief: Send the result of this form to a flat file on the local file system.

Dependencies: A form and write permissions to the file save location.

Hints & Tricks: Be sure to set the correct file permissions for the folder/file your writing to!

We can create XMl files that have data appended to them by using XML Wrapper property.

Options/Properties

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.

Flat File Data Composer

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.

XML Wrapper

This property allows us to create valid XML files that are appended to with each form submission. Please note this field only applies to data originating via the Flat File Data field.

To understand what this field is needed, remember that a valid XML file must be wrapped in a single root node. This root node can of course have an unlimited number of children in any valid format, but we must always have one root node.

The problem is when we create a file structure using the Flat File Data field we'll loose the root node after the first submission, as we append data using the templates format to the existing file data. Thus, the root node cannot be part of the Flat File Data field as we'd simply keep writing more root nodes. Remember, we can only have one root node.

The solution is the XML Wrapper field. When we supply a value to this box we wrap it in XML open and close tags (e.g. <>) and prepend and append it to the existing file data.

Now we have our root node, and the XML schema we supply to the Flat File Data box will nest within it properly.

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.

Flat File

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 RackForms 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.

Process PDF Files

When checked, takes any PDF file generated by RackForms and sends to the location defined by File Location & Name. PDF file generated by RackForms means any file created by the PDF Output Mode where email is included in the name. Please note when using this mode the PDF file name is generated by RackForms, and cannot be changed.

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 dynamic 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 we 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 this method, RackForms will take the field and PHP variables you set 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.

One special feature of this field is the EXCEL token. When used, RackForms will take all form field items submitted by the user and create a comma delimited file, complete with a header row containing each field items field name. This is very handy as large forms would require a significant amount of work to create such a list.

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.