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.

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.

Module Discussion

Generally speaking the S/FTP module has three modes of operation:

• Send Existing Flat Files
• Send Dynamic Flat Files
• Send Uploaded Files

Flat Files In this mode we simply enter a file path and name into the Flat File Name field. So long as this file exists RackForms will send it upon submission.

Dynamic Flat Files In this mode we've generally taken the result of a form submission and created a flat file based on the user input to the form. A good example of this is an XML or text file. The secret sauce is in order to send a dynamic file we must first create it, which is why in this mode the S/FTP module will be used after a Flat File module call. The Flat File module creates the file, this module sends it to the FTP server.

Send Uploaded File In this last mode we'll take the result of a file upload and send it to the FTP server. The critical component here is telling RackForms which file field we want to send. We so this in the File Upload Field Name field.

S/FTP Enabled

Generally enabled, though can be useful to temporarily disable this feature during testing and development.

S/FTP Logging

When enabled, displays debug and information data on your connection and transfer.

Use Passive FTP

Not used at the moment.

Server Address

The server you wish to connect to. Can be a local machine, such as localhost, or a remote IP or host name.

Server Port

For most S/FTP connections this should be 22.

Login

The login name for the S/FTP user.

Password

The password for the S/FTP user.

Root Directory - Dynamic

The directory we wish to upload our file to. Can be blank, in which case the login users home/root directory will be used. If not blank that directory must exist on the system.

In almost all cases a value used here must start with the root directory name, and then with a /.

For example, to save to the path:

/Documents/file.img

We'll use:

Documents/

Flat File - Name

In addition to uploading file upload and pdf templates we can also simply upload a local file from your server. In most cases this will be a file we've created dynamically via the Flat File module, but can also could be any file the server has access to.

To support dynamic file selection this field is accepts tokens, meaning we can can create the file name based on form input or any other dynamic text values we like. Because of this and as noted in the Editor, extreme caution must be used here!

Allowing users the ability to name files means that user could, in theory, create a file that performs some untrusted operation on the machine. If this file is accessible to the web directory, a user could, in theory, call up that file from the browser the same as any other PHP page. Because of this RackForms outright prevents files with the .php extension from being saved, but depending on your operating system many other file types may be callable.

The following guidelines should help mitigate the most common issues, but even this may not be a fully comprehensive list for your environment and security needs. If unsure, do not use dynamic file names!

• Never allow the file extension to be PHP, or any other executable file format.
• Ensure the destination directory does not have the execute bit set.
• Ensure the destination directory is not world-readable.
• Never use this feature for untrusted (not logged in) users.
• Do not save files to any publicly accessible area, such as your web site tree.

The theme of the list above is to define the following: Uploading files to a server is always a risky proposition: doing so while possibly allowing untrusted users control of the file name is a massively dangerous operation when we're unsure of the security implications.

In summary do not use custom file names for untrusted users, and if we do, make sure the files being uploaded are non-executable and saved to a safe location.

If we understand the security implications the power of this module is in its ability to pluck a freshly generated file from the file system and send it to the FTP server. Critically, this file can have a dynamic name, which means we can create a unique file name for each form submission. For example, assuming we had a form field with the name of Name, we could enter a value in the format of:

flatfile-F{Name}-${timestamp}.txt

This will generate a file on the FTP end in the form of:

John Smith-1596999290.txt

File Upload - Field Field

For upload field transfers this field must contain the valid Name/Value of the file upload field we wish to send. We can assign a custom name to this item in the destination FTP folder via the next property, File Upload Name.

As an alternative to file uploads, when left blank this field will attempt to send any PDF template pages this job contains.

To create a PDF template page, create a standard form page and under its Page PDF Output Properties options set PDF Output Mode to: Save for Email / SFTP Output.

Please note the two modes, file upload and PDF template, cannot be used in the same item. If we wish to use both, create two separate SFTP items, one with this field blank, the other with the name of the field we wish to process.

File Upload - Name

The name we'll assign to the uploaded file on the destination FTP server. By default it's left blank, in which case the file name of the original uploaded item is used or if using PDF templates, the name of the form page. However, we can use tokens in this slot, such as a text field of the name text1 as:

F{text1}

This will take the value a form user typed into that text field, minus and periods or forward/back slashes, and use that as the file name. Care must be taken here however, as this value alone will usually not create a desirable file name, as the value won't typically include a file extension.

For this reason we can also use the hard-coded value FILENAME to insert the original file name. Taken together, we can append a dynamic value to the start of the original file name using:

F{text1}-FILENAME

The FILENAME property is important as our upload files should usually contain a file extension. However, we have one other hard-coded value we can use, EXT, which will resolve to just the extension of the original file. For example, to create a file name of a dynamic text field, the text value OFFICIAL, followed by the original files extension, we would use:

F{text1}-OFFICIAL.EXT