Basic Attributes

HTML 5 Type (text input fields only)

This field, which default to text, allows us to set specific input type values for this field. At the most basic level, setting a type will enable browser based validation, and possibly create extra input controls for the field.

Browser Validation:

While we have a full validation system available to us in RackForms, in recent years browser vendors have taken steps to implement some of the most common validation steps within the browser itself. The Email field is a good example of this, when set the browser will check the validity of the input against common email patterns. If this field is found invalid the browser automatically applies a OS/Browser specific style to the invalid field.

Extra Input Controls

Generally speaking, adding extra input controls such as calendars and color pickers meant downloading and implementing a third party JavaScript solution. With the new HTML 5 controls this work is now implemented directly in the browser. A good example of this is the Date type, when set in some browsers a calendar item appears next to the field.

Considerations

It's very important to note these controls and their implementations vary wildly across browsers and OS's, and even then, not consistently across the same browser over different OS's.

For a current compatibility list please see: W3 Schools.

The good news is if an input type isn't supported the browser simply renders a standard text box.

Label

Type the text you want to appear above or to the side of the form element. This is also the value of the text displayed in the RackForms Result Browser and Email messages.

The label field supports local PHP variables if they are wrapped in PHP tags and echo'd out as: <?php echo $val; ?>

Please note that only local variables are supported, $_SESSION variables must be bound to local variables in the PHP Top Code or PHP Head Code section first.

As of Build 693 the functionality of this item has been expanded to support dynamic tokens for E-Commerce items. Please see the in-editor tooltip (located just above this field), for specifics.

As of Build 701, this field now also accepts the standard RackForms 2 token set for form field labels. Please see the in-app tooltip for exact values to use.

As of Build 705, this field now accepts the standard RackForms 2 token set for Section/Headline Text and Body Copy elements. That is, we used to only be able to use the @{value} token, as can now use F{}, S{} and so on.

The 'new' tokens will, by default, transform linebreaks into HTML br tags. This is very handy when we want to display a text area to a user where such line breaks have been added. This ensures the typed value matches, as closely as possible, the display.

Also in Build 705 is the 'raw' field token: FR{field_name}. This token was created because by default, when we use a F{} token for say, text1, we are actually creating the following code:

<?php if(isset($_SESSION['qs']["{$_SESSION['entry_key']}"]['text1'])) { echo "{$_SESSION['qs']["{$_SESSION['entry_key']}"]['text1']}"; }?>

That is, a full (but inline) PHP block. This makes it impossible to create custom logic in a Body Copy or Section Text block, as the open and close PHP blocks break any such custom code.

Thus, the raw token only places the raw field value into the text data, nothing more. The same text1 item now looks like:

$_SESSION['qs']["{$_SESSION['entry_key']}"]['text1']

That is, no PHP block, and no isset().This means we could, for example, create the following logic in a Body Copy element:

<?php
if(isset(FR{text1}) && FR{text1} != "") { ?>
I want to hide this Bodycopy if @{text1} is empty ?
<?php } ?>

Tail Text
Tail Text allows us to add text just after a text field element. Generally speaking this is useful for adding definitions to the data being entered, such as lbs, psi, and so on.

The content in this item is enclosed in a span with a class of tailtext, and is thus best used for small images and blocks of simple text.

By default the text container is defined in formpage.css with a rule of:

.tailtext { font-size: 75%; }

This means the text will usually be smaller than the label field by a small amount. However, we can certainly add our own html and inline styles to this element for a more custom look.

Name/Value

This element is set by RackForms automatically, though it is recommended to change this value if you decide to display Javascript validation messages, as the 'identifying' text of the error is the value of this field.

This value is displayed by default if no 'Label' attribute is assigned to the element. For technical users, this element name is in fact the same as the Name/Value html form attribute of this element.

You will also notice that if you change the name of this field, the id attribute to the immediate right of this element also updates with the same value. This is because in most cases you should keep the same value for both elements--however, you can use a different value, simply type in the id field separately.

Naming Convention Note: The only valid punctuation for the Name/Value and id fields is the underscore _. Use of any other character will cause the form to fail.

id

By default is assigned the same value as the Name/Value element, though you can change this to a more field specific value. Not necessary for most applications. For technical users, this is the id attribute of the field item.

Wrapper Class Name

Every field element in RackForms is wrapped in either a LI or DIV element for Sortable or Free Form page types, respectively. When you place a value in this box it becomes the class="" attribute for that wrapper. Because a wrapper encompass both the input element and wrapper, you can use this value to show and hide sections of your form.

Helper Text

This text displays on the bottom of the field item. By default, the text is 7pt and light grey #888888. You can change the elements color in the RackForms editor, but the font size must be changed in the jobs formpage.css file.

Default Value
[Only used with text element such as text box and text area]
Any pre-assigned values for this element should be typed into this box. At run-time this value is automatically populated into the field item.

Please note this area can contain a mix of tokens and standard text. This means we can have:

F{name}-entry

...and any non-token characters, in this case: -entry, will be included as well. Pay special attention to spaces, as they will be rendered along with any tokens!

There are a few special considerations with using PHP variables in this field:

1. Always wrap the full variable in braces.

2. You cannot execute functions in this block, only variables.

3. $_SESSION variables must use single quotes as in {$_SESSION['variable']}, not double quotes as in {$_SESSION["variable"]}

4. All variables are passed through htmlentities($variable, ENT_COMPAT), which means any double quotes are turned into &quot;

Placeholder Text

This value appear within a text box field item.

Tail Text

This value appears just after the form field input element of a text field item.

Field Width

In pixels units, the height of the field item. Default of 140 for text boxes and 200 for text areas.

Please note that File Items do not use pixels but rather the html size="" attribute. This means we want to be careful when changing these values, as inputting a value that makes sense for text boxes, such as 200, will be massive for file items.

Field Height

The height of the field, in pixels.

Apply To All Items - Both Field Width and Field Height have this convenience shortcut that when clicked, will make all other items on that form page the same width or height as the current item. This is very handy when we want to quickly apply the same look to all elements on that page.

TinyMCE Editor
[Text area only]

Select from three TinyMCE preset configurations:
Simple Editor - Provides basic text controls.
Text Heavy - Provides ~13 text editing tools plus a slew of editing control such as undo.
FromBoss Style - Creates the same suit of text editing tools used in the RackForms Editor.

* Please be aware that at this time the Display Field Count validation property has no effect on text areas that use TinyMCE. You can still set a maximum character count, but this value will only be validated at the time of the forms submission via PHP, not JavaScript.

** You can only use 1 style of TinyMCE text editor per form page. The text area that comes first in the form will determine which TinyMCE text editor configuration is used.

Readonly

When set this field can contain a value and will submit data when the user clicks the submit button, but its value cannot be changed by the user. Please note this value can still be changed by manually editing the field in a JavaScript/Web debugger, so please be sure to not place sensitive information that cannot be changed in this field.

Field Enabled

When Yes the field accepts values and input from the user. When set to No the field ignores user input, and its value is not submitted with the form data.

User Provided Value Populates Field

When Yes the field populates with values set by the user after a page load. When set to No the field never displays values set by the user accross page loads.

While a bit strange sounding at first, "why would we not want to show a value set by the user", this has very  useful benefits for more advanced forms, particularity ones that perform data lookups. Say we have a form where we ask the user to input an invoice number for an inventory lookup system. We  never actually submit the invoice number, we just care about using that field as a lookup. The problem is when we leave the lookup page and come back, this field would now be populated with  the previous query's value. Thus, setting this option so the field doesn't remember the value  can be very useful when we want to keep our UI clean. 

Extra Attribute(s), JS, Event Code, etc

Although similar to a submit button, a button has an html type of 'button', not type=submit, which means when this element is clicked on, your form will not be submitted, but rather you must supply the event to occur.

A common use of this type of element would be to attach a history command such as onclick="history.back()", and then use it on a multi-form page to make navigating back one page easier than using text links.

Add code to your field item by typing it into this box. Code can be JavaScript event code such as:

onclick="alert('Be sure to use Letters only');"

External Library dependent code as in: (Prototype/Scriptaculous example)

onclick="Effect.Fade(this, { duration:.2});"

What's important to note is that the code you create here effects the field element, not the container it sits in. To edit the field container, you need to reference the field name prefixed with 'fb_fld-', as in a text box with an ID of text1 would be referenced like:
fb_fld-text1

Extra Field Style Attributes

This field allows us to define extra style attributes for our form elements such as:

color:#cdcdcd;

It's important to consider that RackForms also applies style data, traditionally as:

font-size:12px; color:#444444; font-family:inherit; width:200px; height:70px;

In short, font properties and height/width are handled automatically via editor properties. Thus, this field is for specifying extra style attributes not handled by the RackForms UI.

This is especially useful for Bucket items, where any style data we apply will greatly enhance the look of a standard bucket, which by default has only size and position styles applied.

Conditional Processing

Conditional Processing Overview
The conditional processing capabilities of RackForms can be broken into two main categories:

Guided - In this mode we use all fields except the Custom Conditional Field Statement text area. That is to say, we use the RackForms user interface to select one element or wrapper to apply dynamic logic to. This could be considered the "easy" mode, in that we write no code to perform our dynamic logic. We simply tell RackForms the properties of the interaction we want and RackForms does the rest.

Custom Conditional Code - In this mode we use the Event Trigger property say which event calls the code we define in the Custom Conditional Field Statement box. This could be considered the more powerful but advanced mode, in that we write our own dynamic logic.

Of course with power comes flexibility, as in this mode we can apply any type of complex logic we need to get the job done. In particular though this code-centric mode is required if and when we want to apply dynamic logic to more than one field item or wrapper class item (items that have the same Wrapper Class property defined).

To be clear: if we only need to apply dynamic logic to one item or wrapper class we use the guided mode. If we need to have more than one item show or hide, we use the custom code mode.

Important Note
Starting with Build 759 we can use the Guided mode controls to apply conditional logic to items on a different page than the one the affecting form field is on.

Please note however, that this capability does not apply to Custom Conditional Code logic, only guided ones. That is, any custom conditional code we write only applies to items on the same page.

Field Initially Visible?

Determines if the form element is visible when the page first loads. Please note that this logic always resets on page load, that is, if a user goes back one page where an element was previously shown it will be invisible again .

This Form Field...

This field and the next allows us to create a condition on the visibility of the field. We enter the Name/Value of a form field in this box, and in the next, the value we check against. If the value matches, we show the field. Please note this only works as a method to show a field, not hide. That is, we still uncheck the Field initially Visible to hide the field, these options simply allow us to show the field based on a condition from another form field. Please note this logic works across pages.

Has This Value...

The value we check to determine a fields visibility. This must exactly match the value the form field will contain. This field is also dynamic, which means we can use standard RackForms tokens to check against a dynamic value at run-time.

Easy Toggle?

Checking this box means RackForms will automatically handle the logic needed to perform the opposite action you set in Then... and If This Field Is: properties. For example, if you set the action of an item to be 'Show', if the condition needed to make this show action happen is revoked, the opposite action will automatically happen for you. So, if the condition is the text '1' must be set in a text box in order to show a second text field, if this 1 is removed or changed, the second text box will be hidden again.

In general we want to keep this box checked, though if you wanted to force a field to always show after an action then leave it unchecked.

Event Trigger

This is the JavaScript event that will be scanned for and then acted upon if activated. Some events are better than others for the various tasks you have. For example, the onClick event is perfect for Checkboxes, whereas the onKeyUp event is perfect for text boxes where a user needs to enter a specific value. Experiment with these values and have fun!

Caution! You may run into a situation where you build a form that enables the event trigger on a specific field, then remove that field later on without updating the Event Trigger's 'binding' to that element.

If this happens your forms validation will break, along with other potential issues.

The solution is always make sure that when we enable an event trigger for an element, that field exists on the form.

Animation?

While not always needed, if you want you can add animation using Prototype JS to your events. The upside of this is your forms may have a more professional appearance, the downside is the extra bandwidth needed to send the Prototype JS library over the wire to run the animations. However, if you are already using animation or have included the Prototype JS library for other purposes, this bandwidth cost is obviously negated, so animate away!

If This Field Is:

This is the core property of the Conditional Processing logic. In most cases you will only want to show and hide fields if a specific condition is met, this option allows us to set that condition. As with the Event Trigger property, some options only make sense in the proper context. For example, the top Value Comparison grouping is best served in combination with text and select fields, whereas the Field State options of Checked and Unchecked only make sense for checkboxes.

It is also important to note that RackForms will attempt to cast comparison values set as INT and FLOAT values to their respective native types.

This Value...

When we set the If This Field is property, with the exception of the two Field State checks of Checked and unchecked, we typically want to compare against some value. It is in this text box that we set that comparison value. RackForms will automatically attempt to detect FLOAT and INT values when testing against GREATER THAN and LESS THAN checks.

Then:

If the condition set in If This Field Is and This Value... passes, this is the action we will perform. Please note that is Easy Toggle? is enabled, we will automatically perform the opposite when the check fails.

This Field Or...

When we set an event, comparison, and action, the last step is to tell RackForms which fields to act upon. It is in this field and is close relative, This Wrapper Class, that we set this field or fields.

As you build your form RackForms will automatically track the Name/Value properties of the elements on that form page and then present them to you in list format in this field. Thus, all eligible form fields will be displayed in this select item, the one you select will become the field acted upon.

Finally, any elements that are set to hidden on page load are tagged with a [H], which makes it easy in many cases to see which items you may need to work with.

Note that items from other pages will be shown as well, they are grouped with an entry of the page name they below too.

This Wrapper Class

Similar to the This Field Or... property, with the exception that instead of single field we can act upon all elements with the same Wrapper Class attribute. This makes it very easy to show and hide large portions of content with one action, perfect for address fields and the like.

Conditional Field Statement

Although RackForms tires to automate as much of the show/hide process as possible, their will be times when you need to have more complex logic. When this is the case, we can use the simple RackForms API to create custom logic.

The bulk of this logic will be derived from a JavaScript object called fbc. This object is defined in:

/rackforms-root/app/movefiles/conditional.js

This file is exported into the root of all RackForms jobs.

The basic usage of this object will depend on what action you want to perform. Their are 4 methods you need to know about:

hideField, hideWrapper, showField, showWrapper

As shown in the editor, we call these methods as:

fbc.showField(event, 'FieldName', 'animation');

With a simple example to show a text box being:

if(in_value == '1'){
  fbc.showField(event, 'text2'); // animation argument is optional, event and field name is not!
}

Simple enough--But it is important to understand that at the page code level RackForms creates two distinct but related items.

The first is the event trigger which is placed inline with your form element. Please be aware the event used is not created automatically, you need to select one from the Event Trigger select item.

Thus, if we select the onKeyUp event RackForms will place this code inline with your element:

onkeyup="fb_dyn_text1(event, this.value, this)"

Notice we have three arguments. This is important because the inline method call is directly tied to the second main element RackForms creates for you, which is a script tag with that methods definition.

This method looks like:

function fb_dyn_text1(event, in_value, elt){
  if(value == '1'){
     fbc.showField(event, 'text2');
  }
}

As you may now see, this method body is the code you create in the Custom Conditional Field Statement text area. The reason why it is wrapped in the method is to that you do not need to worry about creating or gathering the event, in_value, and elt parameters.

Thus, the last bit of knowledge to convey is that these parameters, event, in_value, and elt, can be used in any way you need in your Custom Conditional Code. Most of the time you will only need the in_value parameter for your logic, but please notice you must pass event to the fbc functions no matter what.

Custom Code Hints and Tricks

Place hide field calls at the top of the code section.

One common trick to employ to keep your code block clean is to place all hide calls at the top of your code block. This eliminates the need for most if/else blocks, and means we only need to set conditions to show elements. The reason this works is hiding and showing elements is so fast, that even if an item is shown and will not be hidden by the code, the hide call and subsequent show happens to fast to be perceived.

Be careful with integer values.

Integer and number values in JavaScript can often cause problems, as they may be interpreted as strings, and vice versa. Thus, when working with number values always pass them through isNaN (is not a number), and parseInt/float. For example, the following code will check to make sure k is a number, and is also an int.

var k = 10;

if(!isNaN(k)){ // is this a number?
  if(parseFloat(k) <= 10) { // parse and check value
   console.log(1);  
  } else {
    console.log(0);
  }
}

Watch which Event Trigger we use.

Generally speaking, a text box should use blur, a drop down onchange, and radio and checkbox items onclick. Using different events is possible, but can lead to unexpected results.

Callbacks

New in Build 711, we now have a callback that's fired after an animation plays:

animationDone(elt)

We use this callback inline with our Conditional Code block as in:

fbc.animationDone = function(elt){
  alert(elt.id);
  // when animation is done, call resize function for iframe
  window.parent.resizeSubForm(getOutputSize());
}

That is, we call fbc.animationDone(elt), then in that function, define the actions to take place.

The elt parameter is the object that called the animation, that is, is the object which reacted to the event.

Please note this event is fired for every animation that plays. Thus, if we've used this in the content of a Wrapper Class with say, 5 elements, this function is called 5 times.

Important RackForms Note: In RackForms 2 the in_value parameter was defined as just value. This caused code conflicts however, and was thus renamed to the present value. If importing any RackForms 2 jobs into RackForms, any custom code will need to be updated to use the new value.

Datasource

Dynamic Query (Select Items Only)

You must set this to Yes if you need to run a dynamic query on this item. Running a dynamic query means your list values will be populated by this query, so be sure to only use one column in your SELECT statement*.

We can select and then use use two columns in the SQL select statement. One column queries are fully backwards compatible, and if used you do not need to do anything extra--simply create your query as normal.

If you would like to use two column queries you must be careful of the order of the field list. The first column given in your Source SQL will be used as the display name of the field, the second column will be set as the value. Only the value is transferred through the system and given as a variable to your confirmation page elements, in other words, the option text is for display purposes only.

DB Vendor

Choose the database vendor you will be connecting to for the dynamic query.

Source SQL

Source SQL is the query to run on the select item. Can be inline sql, a stored procedure call, or a 'prepared statement' SQL string.

A simple query might look like:
SELECT make from cars

An example of a MSSQL/MySQL stored procedure call with no parameters would like this:
call sample_proc

A MSSQL/MySQL stored procedure call with one 'int' parameter would look like so:
call sample_proc(10)

To use a non-integer as a parameter surround it with single ticks as in:
call sample_proc('hi')

Please note that if we use double quotes as in:

SELECT * FROM states WHERE state = "Wisconsin"

We must escape the quotes manually as in:

SELECT * FROM states WHERE state = \"Wisconsin\"

In general the safest route is to not use double quotes in SQL statements, as RackForms will never escape them.

To load several parameters use:
call sample_proc(1, 'matt')

More on calling MSSQL stored procedures here. More on MySQL stored procedures.

Prepared Statement SQL String means we use inline variable(s) in the SQL code to pass dynamic values. We do so as in the rest of RackForms, by using question marks (?) in place of actual values. We then define the value of these placeholder values via the Source SQL Parameters block, defined below.

It's important to note this functionality is only used for text fields when using Auto Suggest logic, and for Select items.

Parameter Order

This field determines the order in which our query populates the form field item from the columns returned by our SQL query. By default (and historical convention), we use the convention: label:value. This means the first column returned becomes the form field items label, the second its value. For most queries this is fine, though for some queries we need the opposite. Consider:

SELECT DISTINCT(set_id), set_title FROM t5_question_sets

In SQL, we cannot use DISTINCT anywhere but the first column, which means if we want to use set_title as the fields label, we need to set the label as the second value populated, and the value the first. This is exactly what this option allows us to do.

Source SQL Parameters

This field lets us define the parameters to pass to the database query when using prepared statements. This means our SQL block will contain code that has placeholders in the form of question mark characters, for each of those items we define the value here.

These values must be standard RackForms tokens, which are defined in the Datasource tooltip.

Default Select Value (Select, Radio, and Checkbox items only)
New to Build 705, this value will be passed to the select item creation/population logic, and if a value (match) is found with the incoming data, and provided we do not already have a user-selected value defined, this value will become the select items default value.

This value can take one of two forms:

1. Token: We can use the standard RackForms 2 token set to drive this field. This means: S{}, F{}, G{}, P{}, and ${}.

2. Simple String: Sometimes we do not want to use a dynamic value to set the default value, but rather just a known string. For example, we create a dynamic drop down list of states, and as the form will be mainly used by citizens in Washington State, we set that as the default value.

These values can be pipe delimited strings at which point RackForms will explode the string and match any items in the list it finds, or if it's a simple string value at which point we just match one item.

This is true for database and simple string values.

DB Host Name

The host of your SQL provider - could be 'localhost', an ip address, or a server/instance name.

Please note that for MSSQL we only use one backslash (\) to separate the server/instance.

Database Name (formerly known as: DB Schema Name)

The Database catalog you wish to query.

MongoDB Collection Name

The name of the MongoDB collection we wish to query. This is a required field for most Mongo queries. Please note that if this collection doesn't exist at runtime it will be created, as per MongoDB spec.

User - Dynamic

Database user name

Password - Dynamic

The password for this database connection.

Socket - Dynamic

Can usually be left blank, as the socket setting will be defined by the server. However, some server are not properly configured, and in those cases we may need to manually specify the socket path.

Port - Dynamic

Much like DB Socket, this value generally needn't be set. However in those cases where needed, the port value is set here.

DSN- Dynamic

This option is only used for ODBC connections. ODBC connections are extremely powerful, as they allow us to connect to virtually any database server in existence. So long as your database provider supports ODBC, you can connect and query it from RackForms.

ODBC connections can be made in one of two ways: Using a data source name, or using a direct connection string, often refereed to as a DSN-less connection.

Using a data source name:

At the most basic level, if we've set up a DSN in say, The ODBC Data Source Administrator application, this value can just be the DSN name.

For example, if we've created a data source name of: Production_Data, the value we place in this box is exactly that: Production_Data. The name alone suffices to point to the proper server and possibly connect, as the bulk of the connection details were defined when we created the data source.

Using a DSN-less Connection String

If we do not have a DSN, this value will be a driver definition block (connection string). The typical use-case here is when we do not have access to, or do not want the extra overhead of, creating and deploying DSN's on our client machines. Connection strings allow us to define the database properties "on the fly", which means the machine we're running on does not need to know about specific ODBC connections.

Connection strings take the form of name value pairs. The one gotcha often associated with these connection strings is the first element of the connection string must define which driver we're using.

For example, Microsoft Access would use:

Driver={Microsoft Access Driver (*.mdb)};Dbq=mdbFilename

SQL Server would be:

Driver={SQL Server Native Client 10.0};Server=server;Database=AdventureWorks;Trusted_Connection=yes;

The key here is the Driver={} part, the name between the braces must be the exact name of the ODBC driver loaded on your machine.

Finding this name is quite easy on Windows, simply load the ODBC Data Source Administrator application and click the Drivers tab. The value in the Name column is what we'll use. In we're running a Mac we can download ands use this tool.

Finally, even with a proper DSN or connection string, we may still have to define a DB User Name and DB Password. If at first you cannot connect, supply these two values and try the form again.

DB Connector File

If you input an absolute path into this box, RackForms will use that file for all database connection information for this query.

MySQL SSL Options

RackForms supports secure MySQL connections using SSL. To enable this functionality your MySQL Server will need to support SSL connections, which usually means modifying your servers my.cnf file to supply locations to your ca, server-cert, and server-key file. You may also, depending on your MySQL version, need to enable SSL connectivity. Learn more about this process and settings here.

As a very brief demo, the my.cnf settings we use internally are as follows:

ssl-ca=/mysql-ssl/ca.pem
ssl-cert=/mysql-ssl/server-cert.pem
ssl-key=/mysql-ssl/server-key.pem
ssl

Once the server has been configured to allow SSL connections, RackForms will need to know the location of three key files. These items are described below. To keep things simple, the names used in this document assume we've created our keys using the process described here. Please note the .PEM file locations can be relative or absolute.

MySQL Client Key File

The client key file will be called client-key.pem. This is our private key used in the SSL handshake process.

MySQL Client Certificate

The client certificate will be called client-cert.pem, and is used to publicly identify us using the CA file on record.

CA Cert

The last file will be called ca.pem, and is a "shared" file between the server and client, as in we use the same file.

As an example then, if I created a folder called mysql-ssl and placed my .PEM files within, the values I'd use in RackForms would be:

MySQL Client Key File - /mysql-ssl/client-key.pem
MySQL Client Certificate - /mysql-ssl/client-cert.pem
CA Cert - /mysql-ssl/ca.pem

Important Notes On MySQL and SSL Support

Using localhost: First, when using a localhost setup we'll often use localhost as our Database Host Name. The problem with this is on a local machine localhost uses sockets instead of TCP/IP, which means we're trying to encrypt a local communication channel. This simply doesn't work and we're receive a "doesn't support SSL/crypto" message. The solution here is to use 127.0.0.1 as our host name, which forces TCP/IP on a local connection.

Using Self-Signed Certificates: One common approach we may take when using SSL and MySQL for the first time is to set up a test instance on a localhost machine using self-signed certificates. This is great in concept but unfortunately creates some unique challenges. When we try and connect we may be greeted with the error:

SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

The problem here is new security features in PHP 5.6 and above, along with the MySQL native driver, creates verification issues when using self-signed certs. If this is the case we can disable certificate validation using the Verify MySQL SSL Server Cert option.

Verify MySQL SSL Server Cert

As noted above, when using self-signed certificates it may be necessary to disable certificate peer validation. This option should always be set to Yes in production environments, but if you have problems connecting on a local network or machine, try the No setting.

It's very important to note setting this to No completely defeats the purpose of using SSL, and should only be done on a non-production, local machine.

If you've made it this far we should only have one final consideration, the encryption cipher:

MySQL SSL Cipher

When connecting to a MySQL server using SSL, the client and server need to negotiate an encryption protocol and cipher. In the best case scenario this happens automatically, and the end result is the server automatically selects the most secure grouping possible.

Unfortunately this doesn't always work (especially when using self-signed certificates or builds of MySQL compiled against older versions of OpenSSL). The most common case is when your MySQL server only supports TLS V1, in which case the default cipher (DHE-RSA-AES128-GCM-SHA256), is not supported. If this happens you'll need to choose a different cipher from this list. The best way to do this is to start with the lowest value in the list, then work your way up until it fails again. Then, back down to the last working option.

The general rule will be if the default option fails, none of the 256-bit variants will work. This is usually considered a security issue, and you should take steps to update your MySQL server and/or PHP version to ones that support the latest security protocols.

 

Apply Settings To All Datasource Items...

This handy little button copies the current fields datasource settings to all datasource enabled fields in the job.

This is a big time-saver when we have many datasource items in the job that require the same settings.

A note on connections

If you leave all fields blank and simply supply a SQL call in the SQL Source field, RackForms will by default include the movefiles/config.php file. By default, this file is populated with the RackForms Schema connection info.

If you provide a value to the DB Connector File field, the config file is not moved to your final job folder and connection info comes from that file.

Finally, if you use inline connection information, that will be used in the absence of any other fields. in short, the connection variable precedence is:
1) DB Connector File
2) config.php
3) inline variables

SQL Debug Mode

Enabling debugging will show error messages for your queries. Please note that for SELECT items you will need to view the page's source code (usually done by right clicking on a blank part of the page and selecting view source) to see any error messages. This is because the error messages are embedded in the SELECT items options field, which will not show in html.

Populate Using Web Service (Select Items Only)

In many cases we'll want to use a web service to populate the values of our drop down. This feature allows us to do so. It's basic operation is quite simple, enter a URL to the web service, a method (POST or GET), and provide any Query Parameters and custom headers. Your request runs and the returned data populates the select item in question.

URL

The location of the web service we will call. This should almost always be a secure URL (https).

Method

The request method used for the web service, either GET or POST.

Query Parameters

We can customize our response by passing parameters to the Web Service. Use this section to do so, supplying both a parameter name and value. Please note the Value field can be dynamic, accepting any standard RackForms token such as F{} for form fields and ${} for PHP variables. Of course if we do make use of user-supplied variables extreme caution should be exercised! We'll want to make sure no data can be returned that's unsafe for a given user, doubly so if the query returns sensitive data.

Query Headers

Use this section to supply values for logins and other custom logic. The most common will be for authorization, a few examples may be:

Key	Value
Authorization	Bearer <ACCESS_TOKEN>
Authorization	Basic username:password (value usually Base64 encoded)

Developers may notice when creating raw header tokens we separate the key and value with a :. RackForms adds this for us, so our values need only be the "raw" data.

Web Service Data Format Hints

When creating a web service for consumption using this method it's important to know the best way this data should be formatted for optimal results. In general, a select field can have a value only, or a separate label and value. When using value only, the value is both the select items label and value. When using a separate label and value, the label part becomes the option label which is visible to the user, and the value is that options value part.

RackForms supports XML and JSON result data, this section shows each in turn to highlight what the resulting select field would display.

JSON Data

Let's start with JSON data. Given this JSON data:

[
  [
      {
          "First Array": 1
      }
  ],
  {
      "Second Array, First Value": 2,
      "Bob Johnson": 2,
      "Bill Smith": "Fourth Value",
      "Sally Fields": false
  }
]
  

The resulting select item will have the following HTML:

<option value="1"> First Array </option>

<option value="2"> Second Array, First Value </option>

<option value="2"> Bob Johnson </option>

<option value="Fourth Value"> Bill Smith </option>

<option value="false"> Sally Fields </option>gt;

The first item of note is the JSON result has 5 items and thus our select menu does as well. This is despite the fact that the JSON data is broken into 2 separate arrays. Critically, RackForms does not care about data organization in the returned data, it simply pulls all valid records it can.

The next item of importance is the relationship between the JSON data's key / value structure and how that maps to our select field's label / value. For example, the First Array element has a value of 1, and this structure is indeed reflected in the generated <option> element.

XML Data

For XML data we run through the same "greedy" process, meaning we do not care about structure, but rather just pull all entities we can to generate select options. So for this XML we'll generate the options as:

<?xml version="1.0" encoding="UTF-8"?>
<employees status="ok">
   <record man_no="101">
      <name>Joe Paul</name>
      <position>CEO</position>
   </record>
   <record man_no="102">
      <name>Tasha Smith</name>
      <position>Finance Manager</position>
   </record>
</employees>
  

Resulting option HTML:

<option value="ok"> status </option>

<option value="101"> man_no </option>

<option value="Joe Paul"> name </option>

<option value="CEO"> position </option>

<option value="102"> man_no </option>

<option value="Tasha Smith"> name </option>

<option value="Finance Manager"> position </option>

Internally RackForms converts all XML to JSON before parsing the results for option creation, meaning the rules by which we parse the result are in part governed by that conversion process. The upshot is both XML fields (nodes) and properties are respected, and we use the following rules to map values:

XML Properties

For properties, the property identifier becomes the option field's label, and the property value becomes the option value.

status="ok" is converted to: value: ok | label: status.

XML Fields

For standard XML field nodes, the label is the node name, and the value is the node's value:

<name>Joe Paul</name> is converted to: value: Joe Paul | label: name

Field Style Properties

Grab This Fields Style Properties
This shortcut button allows us to quickly store and then apply the current fields style properties to other fields.

When we press the button the cursor will turn into a crosshair. To apply the style settings to a new element simply mouse over the field and click.We can leave this mode at any time by pressing the Escape Key.

Element z-index

This seting allows us to set the z-index of most items. This property is reflected in the editor as well, making positioning items much more streamlines than in previous versions.

By default most items, with the exception of calendar fields, have a base index of 1. This means so long as your form fields to not overlap you will not need to set this property. However, some fields, such as images or those with popup's (like the calendar field), benefit from setting a different layering order.

Element Tab Index

This option allows us to set the tab index of the element in question. Care must be taken when we set a value however, as items like the Grid Element contain sub elements, and although a set value will tab to the first element of the Grid, if we have elements with a higher tab index after the Grid we'll immediately tab out of the Grid item.

As a general rule when we build forms the tab index is automatically decided by the browser based on document position. That is, the newest elements we create have a higher tab index. This is different than visual position, as if building a free form page the lowest element on the page may not be the newest created.

Thus, the tab index control helps us smooth out visual position and actual tab order by manually being able to set it.

Sometimes a better method however, is to switch a free form layout to sortable and position elements from top to bottom in the order we add them to form. Then we can switch back to free form and while the positions of our elements has been retained, the tab order will now reflect the proper document ordering.

That said, perhaps the most common place to set tab order manually is when we have a Layout Bucket or Survey. This is becuase In some cases a layout buckets items will be added after other sortable items have been added, which means a tab out of a bucket item places us out of the bucket and into the most recent item added.

Text Color

Click into the box to load the color selector. Drag your cursor over the saturation in the main box to select the color intensity, or drag the hue slider to change color.

Input Text Color

Set the input fields color.

Label Font Size (px/pt)

Type a number in this box to change the font size of the element. By default if no unit is specified (the field is just a number) RackForms will use px. We can use pt however, and this unit-type works much better with PDF output in some cases.

Label Font Weight

This option lets us set the font weight of the forms field label or main text block.

Option Font Size (px/pt)

Used only for Radio and Checkbox items, defined the items label font size.

Option Font Weight

Used only for Radio and Checkbox items, sets the weight of the individual radio or checkbox items label.

Field Spans Both Columns In Table Layout

New to build 704, when enabled this option lets the form element in question span both columns in a tablemode layout.

Notes: As of now the only fields to use this option are Section Text, Body Copy, Images, and Separators.

Field Width

This option sets the width of the Section Text or Body Copy elements. Please note this option is not used for any other elements.

Field Height

This option sets the height of the Section Text or Body Copy elements. Please note this option is not used for any other elements.

Border Radius

This CSS 3 feature applies rounded borders to the item. As this is CSS 3 only, IE versions lower than 9 will not be able to display them, though any recent version of Firefox, Chrome and Safari all will.

Item Text Alignment

This option sets the text alignment of the Section Text or Body Copy elements.

Enable Banner Mode

This mode is used to create banner like entities on our form page -- that is, elements that span the entire page width regardless of Page Padding settings. By banner we broadly mean a text display element that has a background color set and any type of content within.

It's key to note that this feature is only useful if we've got a full page form that uses page and form background colors. If we do not have this type of layout, it's almost always best to ignore this feature and just use the standard form padding controls.

If we do have a form that uses background colors, Banner Mode is needed because RackForms applies page padding to the form container. We can control this padding amount via the Form Style Properties > Page Padding control.

In theory we could set this value to 0 and then all text elements, if set to the proper width, would span the entire length of the form page. The issue is if we did all form elements will end up touching the edge of the form page, which of course includes all form elements.

As this is rarely what we want Banner Mode was added to selectively say "this element should span the entire form page, but leave everything else alone"

The end result from a technical standpoint is RackForms, when building the form, takes the page width and adds the page padding we've defined and makes that the new width of the element. It then take the page padding the applies that as negative margin to the element based on the Banner Mode Position setting. Thus, from a presentation standpoint the element now spans the width of the page, but our global page padding setting still holds for all other elements.

In light of this then it's important to note that enabling Banner Mode means the value we set for Field Width is ignored.

Banner Mode Position

This control, along with Enable Banner Mode, tells RackForms where our banner is on the page. If we set this to Top Banner RackForms will apply a negative left and negative top margin equal to the Page Padding value. The field height stays the same. This is of course used for banners we place at the very top of the page.

If we select Middle Banner we apply a negative left margin but not a vertical one. This means the element will span the entire page width, but not affect the items above and below it.

Finally, if we select Bottom Banner RackForms will change the field height of the element to be +21 pixels added to the page padding * 2 + half of the page's Sortable Item Bottom Margin value. In short, the field will get grow by about 69 pixels so that it touches the very bottom of the page.

All of these modes work best and are in fact designed for standard sortable page mode.

The key to this setting is to know that having a page-spanning banner in the middle of the page using the Top Banner setting will result in a banner that "smashes" into the field above it. Thus, we must make sure we set this property properly!

Banner Mode Hints & Limitations

Banner mode works well if we have just a top banner, or a top and bottom banner, but not if we have a bottom banner only. In short then, try and design your forms to not depend on a bottom banner only.

That said, this issue only becomes apparent if we've also enabled Apply Box Shadow. If we haven't we needn't worry about this issue.

Label Position (Form fields only)
Sets the position of the form field label, though the implementation depends on the form field type. Text items switch between being on top and inline, radio and checkbox items the same, only multiple items line up in a row as opposed to vertically. This is how we create survey type forms, for example.

Please note though that when using Inline, by default RackForms uses 100% width for all radio and checkbox items. This means a series of say, 5 radio options should show nicely on a sortable page. However, their will be times when we want to display radio items in columns, such as when we have many options, or when in free form layout mode.

If this is the case, we can always set a specific column width in pixels under: Select Item Options > Column Width

Input Inherits Font Size and Family

This field lets you set the input elements input font and size to match the label field.

Validation

It is very important to note that validation behavior is handled in two places: the field itself, and in the fields containing page properties. Within the field, you can control the elements listed below, such as whether the field is required, the minimum and maximum number of characters, and so on. Within the page properties, you control the style of error, whether messages are displayed, and other such properties. One way to think of it is error handling per field item, and global error handling properties. FIeld item properties are specific to that element, global effects all error properties of that page.

For example, the default behavior of a field that is marked as required is to, when filled in improperly, highlight the field with a color you choose in the Page Properties Form Error Color. In other words, you set the field as required in the elements field properties, but you control the color of the error highlight in page properties.

For more information on what properties you can edit, please see the Form Style Properties and Page Properties of the Sortable and Fee-Form Page types.

Required

Check this box to make this field a requirement for successful form submission.

Required Star Color: In some instances you will want to change the color of the required star. To do so you can use one of two techniques:

Technique 1. Permanent change: Navigate to the RackForms/app/movefiles/ folder and open the formpage.css file and look for the .req-star class definition. You can then change this color to fit your jobs needs. This change is permanent because every job you export will now use this style sheet file and definition.

Technique 2. Per Job Change: Click on the page header to bring up that page's attributes, then add the following style definition to the Page Javascript/CSS Code code area:

<style type="text/css">
  .req-star { color:#dedede; }
</style>

This will override the style definition in the RackForms.css file and use the color you specify.

Field Validation Method

This option allows us to set the behavior of how conditional items will be validated when hidden.

By default, when we set an item to be hidden and required RackForms will still process the invisible item as if it were shown to the user. With this new option we can override this behavior to tell RackForms that any item that's hidden and set with Field Only Validates When Visible should, as the option name states, only trigger validation errors when visible.

The trick with this is from a security standpoint it's possible to create a script that exploits this behavior such that no fields would be required. However, the RackForms implementation is such that only fields set with the property are able to be 'bypassed' via normal validation methods.

The end result then is if we're building a form that needs to have required fields, but those fields are hidden unless a user triggers a condition to show them, to enable this mode for that field, and of course any others that require it.

By default RackForms will still validate all fields unless told otherwise. This maximized security while providing a way to create smarter forms.

Min

The minimum number of characters this field must possess. Validates if the field is required or not.

New in Build 706, for checkboxes, this is the minimum number of items that must be checked for the field to be valid. To set a specific number, set the min and max values to the same value.

Max

The maximum number of characters this field can contain. Validates if the field is required or not. If you wish to limit the number of characters a user can type, specify that value in this field. The user will not be able to enter more characters specified by that value.

For checkboxes, this is the maximum number of items that can be checked.

Regex Validation Rule
This is the Regular Expression rule to apply to this field. Used in required fields only. Choose from No Rule, Custom Rule, and a series of preset rules.

If you choose Custom Rule, you will be given a 'Custom Regex' box to populate with your own expression (please note only one expression can run on each element).

For example, you could use this to validate $45.23:

^\$[0-9]+(\.[0-9][0-9])?$

or without the dollar sign as in 45.23:

^[0-9]+(\.[0-9][0-9])?$

Same As

[Only used for Text and password fields] If populated, this element and the one specified must match to validate. Only effective if the field is required (the must match field need not be specified as required). Effective for user password and email address validation.

Validation Error Message

Type a custom message for validation here, in the event you select a 'Regex Rule' for the field. All other validation messages are handled by RackForms.

Display Count Fields

[Only used for textarea elements] Select from No Counting, Words, or Characters. Select Words or Characters to display a Javascript based character/word counter at the base of your text area element. This item works in conjunction with the Max validation field, though if no value is set it defaults to 500 characters.

Item Options/AJAX Bindings

Click the + to add a field, the X to remove a field, and the Check Mark to make that field the default. Radio items can only have one 'default' selection.

If creating a radio or checkbox group, click the minus sign will add a line break to that row. Please note this is only useful for survey mode (found under: Select item Options > Select Item Layout Mode), as this is the only layout mode that allows for items to flow in multiple columns.

Be aware that by default, the first option to come in 'Add a radio option' has a value of 0. Always create a new definition for the first select item!

Options must be plain text, HTML code such as <span> or other related tags will cause the form to fail. This is done for security reasons.

One very handy tip for database driven items: In most cases when we have a database query driving out select item list, we do not want any other values in the selection list. However, you'll notice that by default, RackForms always creates at least 1 item for you. The trick is that this value is NEVER populated in the real form, it is simply present to let you know that the field needs a value if it is to show. Thus, we must ignore this field if we want the list to be populated exclusively by our database query. If we change the text in any way the field will render. Thus, again, leave this field as is and your form will render as expected, with only your database values.

Creating OPTGROUPS

Create OPTGROUP HTML elements in RackForms using the following item options:

OPTGROUP=LABEL This "opens" an OPTGROUP, taking a single parameter after the equal sign, the label of the OPTGROUP we wish to display. Leaving this part blank (the equal signs is always required, however), means no OPTGROUP label will be shown.

OPTGROUP Closes the previously opened OPTGROUP, required for proper formatting.

Please note creating OPTGROUP's is not currentlly possible for database driven select items.

Dynamic Default Value

This feature allows us to set a dynamic value which will, for the select list, be the default for that field until submitted.

This value can originate from any source that can pass its value as a token.

Resetting Values To Default - It is important to note that as of Build 702 we now have a way to reset the default value back to being blank. To do so, simply press the Delete button when only one item is showing in the select item list. This will reset the value so that it's label is the default value and it's value property is blank for select items or 0 for radio and checkbox items.

AJAX Bindings Note

This field also handles our AJAX Bindings, which means in the AJAX workflow, these are the form field items that will be updated with any data retrieved from the AJAX request.

Use Boolean Values

This checkbox lets us set the value of the checkbox item to be 1, which means when the users selects this checkbox, the value passed to our output functions (SQL+, Email, etc), is also 1. This means you can have a checkbox with a label of say 'Yes, I want to Sign Up Now', but be seen by your confirmation elements as 1.

Please note this technique only makes sense if your checkbox group has one member. If you have a checkbox group with more than 1 member, you will experience inconsistent behavior with respect to filling out this field, then going back to the page with this checkbox group. (Specifically, even if the user only selected one checkbox item, all will now be filled out.)

This is because as far as PHP is concerned, checkbox groups are arrays, with each checkbox Name/Value being the array key. If you have multiple keys which are the same, the process of distinguishing those keys becomes ambiguous, and hence, irregularities present themselves.

Items Per Column

This option lets you decide how many checkbox items you want to display per column. The default is 10, any item after the tenth one then will get placed into a new 'column', the second group of 10 after that the same thing.

Be sure to provide enough room for your checkbox items in the Page Width setting, as too small a value will cause the checkbox items to bunch up on each other.

Column Width

This setting is part-in-parcel with the Items Per Column setting. The number you place in this box will be the pixel width or percent of each check box column. You will want to adjust this vale for optimum spacing of watch column.

By default we set this to 100%, which means Inline groups of items simply span the entire page width. This makes it easy to create surveys in sortable mode, but this format and style may not be the best for free form pages.

Thus, we can always set this value to a specific pixel value.

Label Margin

This value is empty by default, but when set, adds a left margin to the elements label. This has the effect of "pushing" the label away from the input element, which can be very helpful when using larger label sizes form elements (such as when using a scale transform on the field input.

Select Item Layout Mode

When set to the default of Standard radio/checkbox items are laid one after the other, the width of the label determining the width of each element. When set to Survey Mode each item can now be set with a specific width, padding, margin, and background color. In other words, the next three options will now apply to the items in this radio or checkbox group.

This is a useful option for, as the name suggests, surveys where keeping all items in a neatly defined column structure aids in readability.

Item Width

The width of each radio or checkbox item. Please note that the Column Width setting must be set wide enough to accommodate all items. This includes all padding and margin as well.

Item Padding

The padding of the item that uses Survey Mode.

Item Margin

The default value of 1 means each Survey Mode item has 1 pixel of margin between each item, which allows users to quickly dedifferentiate between options.

Container Margin

This value allows us to override a form fields Sortable Item Bottom Margin property with a custom value. This has one main use, a sortable form where we have two or more radio or checkbox items that need to appear to be part of the same group. This can happen when we need to have one of the options hidden unless specifically shown. When this is the case, having 0 margin for the hidden item (if on top) will ensure the items remain visually connected.

Custom Label Class Code

The code written to this field will be placed in the individual select items label's class property. This option allows custom code to be written to, among other tasks, apply style sheet classes to the radio or checkbox item based on its set value. Key to using this feature is know that our values can be simple css class selectors, or complex PHP statements that echo out selector names. If using PHP, we can fetch the current items value using the PHP variable $value.

For example, we can use this code to apply a default selector of choice to all items, and then use PHP to inspect the current field value and echo red, green, or gray as needed.

Apply These Settings To All Multi-Select Items

This shortcut button will take the current fields Column Width and all items under Select Item Layout Mode and apply them to all matching radio or checkbox items on that page. This is handy for times when we want all of that page's items to match.