RackForms v7.2.3
survey
Site Tag Line
Latest Release: Build 927 - April 19, 2019
Contact Us  Purchase Options Purchase Options Contact Us
header-image


 
Top Link
Text Field - Survey

In Brief: Create a survey using this module by adding quesitons to the Survey Questions Box.

Dependencies: none.

Hints & Tricks: Unlike other form field items, surveys cannot be hidden and required at the same time. If a survey is required, is will always require all items to be completed to submit.

Options/Properties

Basic Attributes

Label

The text your element displays.

As of Build 701, this field accepts the standard RackForms 2 token set for 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' RackForms standard tokens will, by default, transform line breaks 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().

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

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.

Conditional Processing

Field Initially Visible?

Determines if this field is initially visible to your forms users.

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 initialy 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 runtime.

 

Field Style Properties

Element z-index

New to Build 697, this feature 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.

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.

Font Size(px)

Type a number in this box to change the font size of the element.

Label Font Weight

New to Build 685, this option lets us set the font weight of the forms field label or main text block.

Element Position

Use this control to position an element to the right of the page, as opposed to the default left.

Label Position

Has no effect for this field. Might be implemented in later versions.

Survey Options

Survey Questions

These are the quesitons we ask the users. Each question must be on its own line.

Survey Responses

These are the possible responses to each questions in the survey. Typical values will be along the lines of good, better, best, and so on.

Each answer must be on its own line.

Create Survey Questions From Database Call

This feature allows us to:

1. Place content in the Survey Questions field from the result of a database query or:
2. Generate surveys questions dynamically when the form is viewed by a user.

How this feature is used is dependent on the Generate Database Questions At Runtime option, described in more detail below.

The default behavior is to take whatever we've placed into this box and run that query every time the page is loaded by a form user. In other words, the "source of truth" for the content displayed will always be the current database values.

In contrast, should we disable Generate Database Questions At Run time (set it to No), this feature becomes more of a one-off convenience, in that should we have a database table with questions already present, we needn't copy/patse those values in RackForms; we simply click this button and our questions populate this box.

In both cases the key to this process is the database query MUST include a column named QuestionText, and each row in the database must correspond to one question.

If we do not have a column called QuestionText, we can always alias it using the AS keyword as in:

SELECT QText AS QuestionText FROM Questions;

Once we've entered our query we'll want to click on the Generate Questions link to check for errors, as well as view the output of the query. Please note that we run this query again when we export the form, so any changes made to the database between clicking the Generate Questions button and saving of the form will be reflected in the final output, but only in the form editor when you re-click Generate Questions.

Query A Second Column Of Data

Assume we wish to perform additional logic when we populate our survey items. For example, lets say for each question we ask, we wish to color the background of that item with red or green, depending on weather or not the question is asking an item that has safety concerns. If the item being asked has safety concerns, color the background red, otherwise green.

To support this type of logic we'll add a second column to our database query as in:

SELECT QuestionText, email_trigger AS col2 FROM t5_question_sets WHERE set_id = 0

The second column we query MUST use the alias of $col2. So long as it does, we can use this value in our Item Label Custom Class Code field, described below.

Generate Database Questions At Runtime

When enabled (by default it is) RackForms generates dynamic survey items at runtime. This is vastly different from not doing so, as the entire survey, questions, answers, and validation, is processed when the form is run.

When set to No, the survey based on the database call is created once when the form is published.

The benefit to having this option set to Yes is should our database query change our survey will automatically pick these changes up and reflect them immediately in the published form. The downside is should this database table be removed or changed without us wanting it to be, then our published survey could be wrong as well. The ultimate decision here will be determined by our work flow. if having a dynamic, changing survey is important, then this is an excellent way to keep the two in sync.

Item Label Custom Class Code

This code can be applied to the class element of each survey item. This can be very useful for creating dynamic backgrounds and color values for individual items. Please note the code we include here can by dynamic, but the result of which is always in the class attribute of the label item.

This field contains two provided values for implementing custom logic:

$value - The current value of the survey item being created. We can inspect this value directly and perform custom logic based on its value.

$index - The question number, 0 index based. That is, the first question we create will have an index of 0, the next 1, and so on.

$col2 (optional) - If our database query above selects a second column and aliases it to col2, we can use that value in our logic blocks.

Taken together, we can combine these values into logic such as:

 
<?php 
// For each turn, check the trigger and if set and equal to current value, mark with that color.  
  
echo 'choice '; // leave space at end for additional class names.

if($value == 'Yes') { if($value == $col2) { echo 'red'; } else { echo 'green'; } }
if($value == 'No') { if($value == $col2) { echo 'red'; }  else { echo 'green'; } } 
if($value == 'N/A') { echo 'gray'; } 

}
?>

This code will place a default class name of choice, then switch, based on the current question index, and add a second class depending on which value that row contains.

Trigger Field JavaScript Condition Code

This feature allows us to display an additional field for each survey row item based on a "trigger" condition. Key to this process is we're provided several built-in values that allow for comparison logic that, based on weather or not the conditional passes or fails, shows our additional field. The code used is raw JavaScript, and can be simple or dynamic.

Simple - In this case, the code we write uses the value property provided to us, which is the raw text value of the field the user just clicked. For example, if our survey contains two possible answers, Yes and No, our conditional code could be:

value == 'Yes'

value is provided for us, and will equal the raw text value of the form item the user just clicked on. If that value happened to be the 'Yes' option, they will be shown an additional form field item.

Please note in both cases, simple and complex, we automatically toggle the fields visibility for you. That is, if we show on Yes, we hide the field if the user later clicks on the No option.

Dynamic - The simple method works great if every trigger condition in our survey is the same for every row. That is, if Yes triggers our additional field every time. However, we may have a situation where Yes or No could be our trigger.

In these cases we'll want to populate our survey questions with a database query using the Generate Survey Questions From Database Call field, making sure to alias a second column in our SELECT statement to col2. This second column value will then be available to us as a raw JavaScript variable col2, which can then be used in our comparison.

For example, lets say we have a database table with the columns: QuestionText and trigger. QuestionText will be used to create our survey questions. The trigger column contains a single word value, one for each survey question that will trigger our additional field. Knowing this, we can then write an SQL statement as:

SELECT QuestionText, trigger AS col2 FROM t5_question_sets

Please note how we alias trigger to col2, this step is required!

Now for each survey item, we have an additional field that our comparison code can use. All we need to provide is the comparison code that will ask which field was just selected, and if if matches our dynamic trigger value. Thus, our Trigger Field JavaScript Condition Code would be:

value == col2

That is, value is the raw text of the item just selected, and col2 is the aliases database column trigger. Assuming the user clicked on Yes and the trigger columns value was also Yes, our trigger field will be shown, or hidden if not.

Trigger Field Type

Choose between a text field and a text area.

Trigger Field Required?

Trigger Field Label

The text placed next to the input field. Can be blank if needed, but it's usually best for legibility to have some descriptive text.

Main Survey Item Field Type

Currently, only radio items are supported.

Survey Grid Total Width

The total width of the survey item.

Question Column Width

Set's the width of the question column using this value.

Cell Spacing

The spacing each cell item gets.

Alternate Line Colors

Whether or not to alternate the lines of the survey with different colors defined in the Alternate Line Color setting.

Alternate Line Color

If Alternate Line Colors is checked, the color this alternating line takes.

Header Background Color

The background color of the survey header.

Question Color

The color of the text for the question.

Response Color

The color of the survey response text.

Question Alignment

The alignment of the question.

Response Alignment

The alignment of the response.

Question Font Weight

The font weight of the question.

Response Font Weight

The response font weight.

Saving Results To A Custom Database

Once we've collected our survey responses we'll need to save them to some location. For database inserts, the general pattern is:

a. Take the Field Name as defined by the Common Attributes > Field Name property

b. In the SQL+ item, take the field name and add an underscore plus the question number index, starting from 0, and wrap that in an F{} token.

For example, if our survey item name was: survey_basic, we'd add the following SQL Code:

INSERT INTO fb_demo (name, email) VALUES (?,?)

And this as our Variables list:

F{survey_basic_0}, F{survey_basic_1}

If our question uses a Trigger Field, we use the same start pattern, but then add _triggerField to the end as in:

F{survey_basic_0_triggerField}


So many features, So little time