frevvo Latest - This documentation is for frevvo v10.3. v10.3 is a Cloud Only release. Not for you? Earlier documentation is available too.

Rule Examples

Overview

This chapter contains numerous real world samples of the custom dynamic behaviors you can add to your forms and workflows. Many of the business rules described below are easily created with the frevvo Visual Rule Builder by simply selecting appropriate functions or controls from your forms/workflows using a visual wizard. Rules can still be written with JavaScript in order to build any degree of complex, powerful business logic and integrate with your Web Services and frevvo connectors.


Navigating this Page

This page is divided into the following sections. To search the headings and content, type Ctrl-f and enter a keyword.

SectionSubsectionsExamples
Rule Events

form.load | form.unload | form.activate

Rules by Function



Calculations

Control Types for Calculations | Addition | Multiplication | Calculate a Subtotal | Calculate a Grand Total | Round a Number | String Concatenation

Show/Hide Rules

Show/Hide based on a Control Value | Show/Hide if another Control is Filled | OR Conditions | Multiple Conditional Statements (if-else if) | Show a Tab on a Workflow Step | Show/Hide Submit and Cancel Buttons | Show/Hide Approval Sections on Workflow Steps

Control Property Rules 

Printable | Enable/Disable Submit and Continue Buttons | Enable/Disable a Control | Set Valid/Invalid Property | Set Error Message | Required Field Status in Accessible Forms | Dynamic Label, Help or Hint | Expand/Collapse Section | Select Tab | Next Tab | Pattern

Formatting Rules

Format Money Values to Display in a Message Control | Format Money in Text Controls | European Number Format | TextArea Max Length | Convert TextArea newline to HTML break | TextArea Wrap Long URL in PDF Snapshot |     Split Phone Number

Prefilling Rules

Tenants, Roles, and Users | Initialize Form with Current User Info | Populate Form with Any User's Info | Populate Dropdown with Users/Roles | Populate Dropdown with Roles Assigned to a User | List Users in a Role | List Users in Multiple Roles | List a User's Roles | Verify User | Verify Role | Unique and/or Sequential ID

Signatures

Signature via Web Service | Set Signed Date | Enable Click to Sign for Anonymous User

Doc Action, ADA, Precondition-Related

Conditionally Send Email

Rules by Control TypeSelection Controls

Options | Set Options | Set Options to Control Values | Default Selection | Display Selected Option Label | Clear Selections | Randomize Options | Dynamic Options | Options from a Database | Combobox Options from a Webservice Options from a Google Sheet | Synchronized Dropdowns | Find a Selected Options Index | Filter Dynamic Options | Triggers & Dynamic Options | Search a JSON String | Cascading Dropdowns | Dynamic Control Initialization with JSON

Comment Property Rules | Set Comment Field | Retrieve Comment Value | Set Max Length for Comment Field

Checkbox Control Checkbox Initialization | Display Selected Checkbox Labels | Checkbox isFilled Condition | Selected Checkbox Options in Conditions | Many Checkbox Comments | Set Options for a Checkbox to Values of Another Checkbox | Count the Options Selected | Repeating Checkboxes

T/F Boolean Control | T/F Value as Condition | Set a T/F Value | Clear a T/F Value


Date and Time Controls 

Working with Date and Time Rules

Set Dates and Times | Today's Date and Time | Date/Time Stamp | Create a Date, Time or DateTime Value | Set a Future Date | Set a Future Date Based on Five-Day Work Week | Get Day of Week from DateCalculate a Return Time | Time Zone Adjusted for Daylight Savings

Duration | Age | Stay Duration (Days) | Duration Including Start & End | Duration (Working Days) | Duration between Date/Time | Calculate Hours Apart | Calculate Time Between

Date Conditions Date No More Than x Days From Today | Date No More Than x Days Ago | Show Error Message if Date1 is On or Before Date2 | Display a Date in a Message Control

Checking a Date for Extra Digits | Copy Date, Time and DateTime Values


Repeats 

Show/Hide Controls in a Repeat | Repeat itemAdded Condition | Collapse Prior Items When Item is Added | Dynamically Set Min and Max in a Repeat | Repeat Item Initialization | Repeat itemAdded by Init Doc | Repeat Item Increment


Tables

Table Column and Cell Properties | Show/Hide a Column in a Table | Hide the Minus Icon on a Table Row | Dynamically Setting Min/Max in a Table | Populate Table Rows based on Query Results | Clear Values in a Table | Clickable Links in a Table | Set a Value Based on Table Rows | Count the Number of Items in a Table | Sort a Table by a Column Value


Upload Control

Display Uploaded Image | Dynamically Set Min/Max Properties | Upload Control Required/Optional | Count Uploaded Files | Display Uploaded File Names in a Dropdown | Rename an Uploaded File | Set Max Total Size for Submission


Message Control

Display Form Data | Display a PDF in a Message Control | Method 1: Host the PDF on your website | Method 2: Upload the PDF in frevvo's PDF Mapping tool | Display PDF with mapped fields | Embed a Video in a Message Control

Rules for Integration


Geolocation | Use Google Maps API to Calculate Mileage | Search Popup | LDAP Custom Attributes | REST Web Services

Rule Events

Whether you are using the Visual Rule Builder or editing Rule Code, it is helpful to understand some of the common events that you will use to trigger rules as they can affect the behavior of your forms/workflows. The following examples illustrate the use of form.load, form.unload, form.activate, and form.deactivate events. 

Refer to the When Do Rules Execute section for more information.

form.load

Rules can be used to initialize field values. This is a very useful feature and is often used to dynamically populate dropdown options from a database. Rules using form.load are triggered when a form first loads and when a workflow is loaded from a task list.

Rules using itemAdded only execute for repeat items added when the user clicks +, and for those added from an initial instance document (See Document URIs). It does '''not''' execute for those items that you have added to your form in the Form Designer. You can either add defaults directly via the form designer or add a 2nd rule to your form as follows.

These two rules together initialize the dropdown fields inside a repeat that is already in the form via the Form Designer, as well as those added each time a user clicks "+" on the repeat to add a new item & via initial documents. These controls are initialized based on a value set in another field.

Rule Code
//1st Rule - Default Items
if (form.load) 
{ 
    // The form contains two repeat items by default.
 
    if (department.value === 'Marketing') { 
        Managers[0].options = ['Joe', 'Mary', 'Stan', 'Cindy'];
        Managers[1].options = ['Joe', 'Mary', 'Stan', 'Cindy']; 
} 
    if (department.value === 'Sales') {
        Managers[0].options = ['Lou', 'George', 'Wendy']; 
        Managers[1].options = ['Lou', 'George', 'Wendy'];  
    } 
}
 
//2nd Rule - Items Added
if (Erepeat.itemAdded) 
{
    var index = Erepeat.itemIndex; // which item is this in the list  
    ES[index].value = 'Day'; // default the employee shift to day
 
    // Use options already selected in form.load rule 
    Managers[index].options = Managers[0].options; 
}

In the Rule Builder, designers can specify at the rule level whether or not a given rule is intended for initialization or not. Checking the Initialization Only checkbox on the wizards marks a rule as an initialization rule. If checked, the generated rule will be wrapped in an if (form.load) statement. The rest of the generated rule (conditions, actions, etc) will be contained within this if statement. The rule shown sets the field named name to "Paul" if the value of the Gender dropdown is "male" and the workflow is on the second step.

Rule Code
if (form.load) {
  if ((gender.value === 'male') && (frevvo.step.on('_8yjc0OSvEeafOKEJqSXZcw'))) {
    name.value = 'Paul';
  } else {
    name.value = null;
  }
}

 If this same rule is not marked for initialization, it will behave like an anytime rule which means that it will fire when the form loads as well as a control value change. The generated JavaScript will include:

var e = form.load;

form.unload

Rules including the form.unload event are not yet supported in the Visual Rules Builder and thus still requires some JavaScript. Rules can be used to finalize field values after the users clicks the form's submit button but prior to the Form and Doc Action execution. Rules using form.unload are triggered when the form user clicks the submit button and for workflows when the user clicks continue to go to the next activity or finish to complete the workflow.

One common example use is for an order form order number. You may only want to assign a unique sequential order number to each order submission. You could initialize the form's order number when the form loads using form.load. However, if someone starts filling in the order form but never submitted it you do not want to consume the next order number in sequence if it will never be used. Using form.unload you can assign the number after the submit button click but before the form data is submitted.

Here OrderNum is the name of invisible control.

Rule Code
/*member num */
var x;
 
if (form.unload) 
{ 
    eval('x=' + http.get('http://(your webhost)/json/getNextOrdernum'));  
    OrderNum.value = x.num;
}

If you have a rule in your form that changes any control(s) after clicking Submit, thereby making the form invalid, the form will no longer be submitted and the invalid form will redisplay. This change avoids creating an invalid xml for a successful submission.

This feature is implemented for forms only.

The form.deactivate event is identical to the form.unload event. Whenever a step gets deactivated in a screenflow or multi-user workflow, it is unloaded as well. form.deactivate was added for completeness. The rule in this example will also work if it was written using form.deactivate instead of form.activate.

form.activate

In a desktop browser, users can navigate back and forth between the steps of a frevvo screenflow or multi-user workflow using the Navigation toolbar. Previous and Next buttons are available on mobile devices for this functionality. Workflow designers should consider this navigation when writing business rules. Steps in a screenflow are read/write since they are all performed by the same user and editing is allowed.

form.load is only triggered when the step is loaded for the first time. This is not very efficient. form.activate triggers every time a read/write step is displayed. This makes form.activate and form.deactivate events that give designers a more reliable way to set properties for steps in a screenflow.

Let's take a look at a two step screenflow designed using Linked forms to illustrate these points. Step 1 has 2 text fields, Text 1 is visible and not required. Text 2 is initially not visible and not required. We added a rule in the Visual Rule Builder that sets Text2 to visible and required on Step 2. 

Rule List

Notice that by default the VRB creates the rule on the form.load event.

Rule Code Generated by Rule Builder
var event = form.load;
if (frevvo.step.on('_4neSkLpxEeu1dMbj8N29dg')) {
  Text2.visible = true;
  Text2.required = true;
} else {
  Text2.visible = false;
  Text2.required = false;
}


Let's see what events occur when Step 1 is loaded.

  • LOAD Step 1 – the form.load is triggered since step 1 is being run for the first time. Text 1 is visible and required and Text 2 is not visbile and not required
  • ACTIVATE Step 1 – activate triggers because the step is loaded for the first time.

The user clicks continue and the workflow navigates to Step 2. Note Step 1 is deactivated and unloaded and Step 2 is loaded and activated:

  • DEACTIVATE Step 1
  • UNLOAD Step 1
  • LOAD Step 2 – the workflow is on step 2 – the form.load triggers because step 2 is being loaded for the first time. Text 2 is now visible and required.
  • ACTIVATE Step 2 – this runs because step 2 is displayed.

The user navigates back to Step 1 without filling in Text 2. Note Step 2 is deactivated and unloaded and step 1 is activated.

  • DEACTIVATE Step 2
  • UNLOAD Step 2
  • ACTIVATE Step 1

form.load is not triggered, so Text 2 is not visible (due to initial property value) but it is still required because Step 1 did not LOAD again. When the user clicks Continue to move to Step 2 the screenflow does not move forward.

If the rule is written based on the form.activate event instead, here’s what happens. (In this case, we edited the rule code and changed form.load to form.activate.)

  • The user initiates the screenflow.
    • LOAD Step 1 – the form.load is triggered since step 1 is being run for the first time. Text 1 is visible and optional  and Text 2 is not visbile and not required
    • ACTIVATE Step 1 – activate triggers because the step is loaded for the first time
  • The user clicks continue and the workflow navigates to Step 2. Note Step 1 is deactivated and unloaded and Step 2 is loaded and activated.
    • DEACTIVATE Step 1
    • UNLOAD Step 1
    • LOAD Step 2 – the workflow is on Step 2 – the form.load triggers because Step 2 is being loaded for the first time. Text 2 is now visible and required. 
    • ACTIVATE Step 2 – this runs because step 2 is displayed.
  • The user navigates back to Step 1 without filling in Text 2. Note Step 1 is only activated.
    • DEACTIVATE Step 2
    • UNLOAD Step 2
    • ACTIVATE Step 1
  • The form.activate event is triggered, so the rule runs. The visible and required properties for Text 2 evaluate to false.
  • When the user clicks Continue to move to step 2 the screenflow moves forward. The user fills in Step 2, clicks Finish and completes the screenflow.

For multiuser workflows, form.load and form.activate are triggered when the step is displayed for the first time. form.activate is not triggred when navigating backwards via the Task List as these steps are Read Only. The Activity assigned to the current user will load only once but will activate every time they are loaded in a particular session.

Rules by Function

The examples in this section are organized by the rule's business function, i.e. calculations/mathematical rules, show/hide rules, and rules for various control properties.

Calculations | Show/Hide Rules | Control Property Rules | Formatting Rules | Prefilling Rules | Doc Action, Activity Doc Action, and Precondition-Related Rules

Calculations

Business logic that automatically calculates subtotals, total, and other math functions is easier for your users and prevents mathematical mistakes. Here are several common examples:

  • Expense Report Subtotals and Grand Totals
  • Time Sheets Hours per task, per day and per week
  • Purchase Order line item costs

Control Types for Calculations

When using the Visual Rule Builder for calculations, the expressions must have the same value type as the control. For example, math functions are only available on number, quantity, and money controls. If there is a type discrepancy, the VRB Help Mode will display a "Field type mismatch" error:

Let's say you have two Number controls that take a decimal, and you want to set the total in a Quantity control, which only takes a whole number. This rule is valid in the Visual Rule Builder. However, if the user enters values such that the sum is a decimal (such as "2.5"), the rule will set the value as requested, but will truncate the decimal in the total (Quantity) control, showing the value "2" instead of "2.5".

The Visual Rule Builder supports text-to-number conversion with the function number(). For example, you may want to calculate a total from two Text controls that contain numbers. Set Total to sum(number(Text1), number(Text2)) to convert the Text control strings to numbers.

Addition

Adding two or more values is a common and simple calculation. Let's take a form that has three Quantity controls named Q1 (Quantity 1), Q2 (Quantity 2) and T (Total). We want to add the values in Q1 and Q2 and display the result in the Total field. This rule will automatically fire whenever the user types something in Q1 or Q2 and will set the value of Total to their sum.

Action Wizard

You can use the sum function or just type Q1 + Q2 in the expression field.

Rule List

or...


How it works

 Click to learn how it works...

Click Rule Code to view the Javascript set by the Visual Rule Builder. It uses the standard Javascript assignment operator (=) to set the value of T, and the addition operator (+) to sum the values of Q1 and Q2.

Rule Code
var event = form.load;
T.value = Q1.value + Q2.value;

Multiplication

Multiplication is a common and simple calculation. Let's take a form that has a Price, Quantity and Total controls. We want to multiply Price times Quantity and display the results in the Total field.

Action Wizard

Rule List

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. It uses the standard JavaScript assignment operator (=) to set the value of Total, and the multiplication operator (*) to sum the values of Q1 and Q2. Notice that in this case the VRB has placed the expression inside parentheses. While not strictly necessary in this simple rule, the parenthesis act as a grouping operator to ensure the correct operation precedence for more complex calculations.

Rule Code
var event = form.load;
Total.value = (Price.value * Quantity.value);

Calculate a Subtotal

You can also use multiplication in a Table Control to display a subtotal for each row. The Visual Rule Builder automatically creates the code to handle adding/deleting table rows. Imagine a Purchase Order workflow with a Table control to list the items being ordered. The Table has columns for Price, Quantity and Subtotal. You want to multiply Price times Quantity and display the results in the Subtotal fields for each row in the table. 

Action Wizard

Rule List


How it works

 Click here to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. The Visual Rule Builder uses an if else statement (condition ? Value if True : Value if False) to assign a value to variables (Subtotal_start_index and Subtotal_end_index) whenever a row is added. Then it uses a for loop that iterates over the table setting Subtotal in each row ('i') to the result of the multiplication expression for that row. 

Rule Code
// if a row is added, set Subtotal_start_index to the index of that row. Else, set it to 0.
var Subtotal_start_index = Table1Repeat.itemAdded ? Table1Repeat.itemIndex : 0;
// if a row is added, set Subtotal_end_index to the Subtotal_start_index plus 1, else set it to the number of rows that have a value in the Subtotal column.
var Subtotal_end_index = Table1Repeat.itemAdded ? Subtotal_start_index + 1 : Subtotal.value.length;
var event = form.load;
for (let i = Subtotal_start_index; i < Subtotal_end_index; i++) {
  Subtotal[i].value = (Price[i].value * Quantity[i].value);
}



The sum() function mentioned above will calculate over the entire repeat/table. To use addition to subtotal individual rows, use the "+" operator, i.e. Set Subtotal to Item1 + Item2. 

Calculate a Grand Total

Consider a Purchase Order form with a table that calculates subtotals as described above. Now you want to add a Grand Total field to your Purchase Order workflow. The Grand Total field contains the sum of the Subtotal fields in each row of the table. Add a Money control to your form/workflow and name it Grand Total. Use the Rule Builder to create the rule. The Rule Builder automatically creates the code to handle adding/deleting table rows.

Action Wizard

Rule List

How it works

 Click here to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. The Visual Rule Builder uses a variables (sum_result) in a for loop to get the calculated total for the number of rows that have a value in Subtotal. The value of GrandTotal is set to that variable, updating whenever a row is added or removed.

Rule Code
var sum_result;
//run this rule whenever a table row is added or removed or the form loads
var event = ItemsTable.itemAdded || ItemsTable.itemRemoved || form.load;
sum_result = 0;
//loop through the table when Subtotal has a value, adding each Subtotal value to the variable sum_result
for (let i = 0; i < Subtotal.value.length; i++) {
  sum_result += Subtotal[i].value;
}

Round a Number

A common requirement is to set a display a number control with a specific number of decimal places. Let's say you have a Time Sheet where you collect the number of hours worked per day and total them in a Line Total field. Your form has a table with Number controls for the daily hours and a Number control for the total. When testing your form, you enter values with decimal points and notice the total unexpectedly calculates to a number with many decimal places. This is JavaScript behavior when calculating decimal point addition. You can use the round() function in the Visual Rule Builder to prevent this and round the Total Hours value to two decimal places.



Action Wizard

The round() function takes two parameters - number and decimal digits. In this example, we're adding several control values to get the number so we enter the addition operation inside parenthesis. The decimal digits parameter is 2.

At runtime, notice that Total Hours is now correctly rounded to two decimal places.

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. Because this example is a table, this rule loops through the table to set values on each row. It uses the JavaScript Math object with round function, which is a method for rounding to whole numbers. It then uses exponential notation ('e' + 2, 'e-' + 2) to round to the correct number of decimal places. 

Rule Code
var TotalHours_start_index = TimesheetTableRepeat.itemAdded ? TimesheetTableRepeat.itemIndex : 0;
var TotalHours_end_index = TimesheetTableRepeat.itemAdded ? TotalHours_start_index + 1 : TotalHours.value.length;
var event = form.load;
for (let i = TotalHours_start_index; i < TotalHours_end_index; i++) {
  TotalHours[i].value = Number(Math.round((Mon[i].value + Tue[i].value + Wed[i].value + Thu[i].value + Fri[i].value) + 'e' + 2) + 'e-' + 2);
}


You can also handle this in the Rule Code editor. Use the built-in toFixed(n) function to truncate the result to n number of decimal places.

Rule Code
var x;
x = (Mon.value + Tue.value + Wed.value + Thu.value + Fri.value);
LineTotal.value = x.toFixed(2);

Another approach would be to assign Patterns that limit the number of decimal places.

String Concatenation

The Visual Rule Builder can also handle string concatenation in the function concat(), which takes as many expressions as you want, each separated by a comma. Any literal values used as expressions should be placed inside quotes. For more information, read our documentation on writing rules with strings vs. numbers. In this example, we will create a rule with the Visual Rule Builder to concatenate the First Name and Last Name and display the results in the Fullname field.

Condition Wizard

Action Wizard

Else Action Wizard

Rule List

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. Notice that each expression on the right side of the value assignment is separated by a '+' operator. In JavaScript, the + operator will add numeric values but concatenate string values. See the Operators documentation for more info. The VRB uses the Boolean check in the if condition, but this is not strictly necessary. Writing if ((FirstName.value) && (LastName.value)) would work the same way.

Rule Code
var event = form.load;
if ((Boolean(FirstName.value)) && (Boolean(LastName.value))) {
  fullname.value = FirstName.value + ' ' + LastName.value;
} else {
  fullname.value = null;
}


Show/Hide Rules

Often forms/workflows need fields that are used conditionally, depending on the answers to other fields. For example, if your form requires both a Shipping Address and Billing Address but the user has checked "Shipping Address is the same as Billing Address" then it's nice to not clutter the form with the unnecessary Shipping Address input fields. You can use rules to hide the Shipping Address and show it only when the form user says they are different.

The easiest way to create a Show/Hide rule is to use the frevvo Visual Rule Builder. Here are common reasons for using Show/Hide:

  • Show/Hide a section
  • Show a Message to the user to alert them to either an error or success condition
  • Show a Details Text Area when as user clicks Yes to "Would you like to describe your issues in detail?"
  • Show a Signature or Signed Section when the workflow reaches the approval step
  • Show/Hide a Tab on a Workflow Step

See the documentation for Data Sources and Schemas for details on implementing a Show/Hide rule with XSD controls.

Show/Hide based on a Control Value

Consider a Purchase Order form that contains a Billing Address section, a hidden Shipping Address section a Radio control named DiffShip that asks the question, "Is the Shipping Address different from the Billing Address?" If the Billing and Shipping addresses are the same there is no need to clutter the form with unnecessary Shipping Address input fields. You can use a rule to hide the Shipping Address and show it only when the form user says they are different. This rule will automatically fire whenever the user changes the response to DiffShip and will show/hide the shipping address section. In this example, an Else Action is helpful so that when the form loads, and if the user changes a Yes response back to No, the section will be hidden.

Condition Wizard

The condition for this rule will be the value of the control DiffShip is the literal value "Yes". Be sure to click the toggle to "Enter a literal value" and use the Form Outline to be sure the value you enter matches the control's option value exactly (it is case sensitive.)

Action Wizard

Else Action Wizard


Rules List

How it works

 Click here to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. The Visual Rule Builder creates an if-else statement. Note that the control name "ShippingAddress" is following by the property indicator ".visible", which takes a boolean value of true or false.

Rule Code
var event = form.load;
if (DiffShip.value === 'Yes') {
  ShippingAddress.visible = true;
} else {
  ShippingAddress.visible = false;
}

Show/Hide if another Control is Filled

This rule makes the message control NicknameMsg visible when the user enters a value into the Nickname input text control. It also hides the message control if the user deletes the value in Nickname.

Condition Wizard

This condition makes use of the built-in function "is filled". It will run whenever the control Nickname has data entered in it.

Action Wizard

Else Action Wizard

Rules List

How it works

 Click here to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. The Visual Rule Builder creates an if-else statement using "Boolean" to check if Nickname has a value. Boolean returns TRUE if Nickname has a value, and FALSE if it does not. The VRB uses the Boolean check in the if condition, but this is not strictly necessary.

Rule Code
var event = form.load;
if (Boolean(Nickname.value)) {
  NicknameMsg.visible = true;
} else {
  Nickname.visible = false;
}

OR Conditions

Here's another show/hide example where we are setting multiple conditions to show/hide a message control. This form has a radio control named Facility and a second radio control named CompanyFacility. This rule makes a message control named FacilityMessage visible depending on the selected options. If Boston is selected for the Facility control OR New York is selected for the CompanyFacility control, the hidden message control will display. 

Condition Wizard

Remember to change the "and" to "or" in the Logic expression so the rule will execute if either condition is met.

Action Wizard


Else Action Wizard

Rules List

How it works

 Click here to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. The Visual Rule Builder creates an if-else statement. Notice the use of double pipe characters in the if condition to represent "or". If you were to use the logic "and", you would see double ampersands, "&&".

Rule Code
var event = form.load;
if ((Facility.value === 'Boston') || (CompanyFacility.value === 'New_York')) {
  FacilityMessage.visible = true;
} else {
  FacilityMessage.visible = false;
}

Multiple Conditional Statements (if, else if)

Perhaps you want to show and hide different controls for each option selected from a dropdown or radio control. The Show/Hide rule structure is very similar to above. However, since selection controls can have many options, you need multiple Visual Rule Builder rules. Alternatively, you can use a JavaScript rule to put all of the switch cases in a single rule using if and else-if statements. It's a good idea in this case to set the values to null on the same switch case where they are hidden. Otherwise, if a user enters data and then changes their original selection, unwanted data may be passed via the hidden controls. 

Rule Code
if (SearchBy.value === 'Organization') 
{
  OrganizationName.visible = true; 
  FirstName.visible = false; 
  LastName.visible = false; 
  ClientID.visible = false; 
  FirstName.value = LastName.value = ClientID.value = null; 
} else if (SearchBy.value === 'Individual') 
{ 
  OrganizationName.visible = false; 
  FirstName.visible = true; 
  LastName.visible = true; 
  ClientID.visible = false; 
  OrganizationName.value = ClientID.value = null;
} else if (SearchBy.value === 'Client ID') 
{ 
  OrganizationName.visible = false; 
  FirstName.visible = false; 
  LastName.visible = false; 
  ClientID.visible = true; 
  FirstName.value = LastName.value = OrganizationName.value = null; 
} 

To achieve the same result using the Rule Builder, create 3 separate rules - one if the choice is Organizations, a second rule if the choice is Individuals and a third rule if the choice is Client ID.

 Click here to see the rules in the Rule List


Show a Tab on a Workflow Step

Tabs are often used like sections to show controls in a grouped view. You may want to display a particular tab only on the relevant workflow step. In this workflow, there is a Tab control with two tabs: Employee and Review. This rule makes the Review tab visible only when the workflow is on the Review step (Step 2).

Condition Wizard

This condition makes use of the built-in condition "current step", which has several options available such as "is", "is on or after", or "is before". The expression field will show a list of available linked steps in your workflow. 

Action Wizard


Else Action Wizard

Rule List

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. In this if-else statement, notice the use of the special frevvo function "frevvo.step.on()". The value in parenthesis is the step's GUID. 

Rule Code
var event = form.load;
if (frevvo.step.on('_b8Le0KLjEeumC5vM65nqTg')) {
  Review.visible = true;
} else {
  Review.visible = false;
}

It can be a little tricky to find the step's GUID if you are writing a rule in JavaScript from scratch. One option is the start the rule in the VRB (to get the GUID) and then switch to Rule Code to finish it. Another is the use built-in data and a variable so you can specify the step name rather than GUID.

Rule Code
var event = form.load;
var an = _data.getParameter("flow.activity.name");
if (an === "Review") {
  Review.visible = true;
} else {
  Review.visible = false;
}

Show/Hide Submit and Cancel Buttons

You may want to hide the submit and/or cancel buttons on your form under certain conditions. For example, consider a form with multiple tabs. The main tab contains the form and the other tabs contain reference information users may need when completing the form. You only want the submit and cancel buttons visible when the user is in the main tab. This rule hides the submit and cancel buttons when the reference tabs are selected. The control name of the main tab is MainTab. Be sure to select the Main Tab in the designer and then save the form. This ensures the Main Tab will be selected when the form loads and the rule will run.

There are two ways to write this rule.

  1. You can write the rule using an if...else conditional statement.

    Rule Code
    if (!(MainTab.selected)) {
        Submit.visible = false;
        Cancel.visible = false;
    } else {
       Submit.visible = true;
       Cancel.visible = true;
    }
  2. Or, you can use a shortened syntax as in this example.

    Rule Code - Shortened Syntax
     Submit.visible = Cancel.visible = (MainTab.selected);

You cannot hide the Continue and Finish buttons on workflows.

Show/Hide Approval Sections on Workflow Steps

A very common workflow pattern is an approval workflow that routes a single linked form to one or more approvers. In this case, you most likely want to show each approver's section only on their step. 

When you create a workflow with approval steps using the Workflow Design Wizard or Guided Designer, approval sections and their associated rules are automatically created for you.

You are designing an Expense Report workflow that has a total of 3 steps. Steps 2 (Manager Approval step) and step 3 (Accounts Payable step) are Linked Steps.

  • Step 1 is filled in by the employee. When it is completed, the workflow is routed to the employee's manager for Approval/Rejection
  • Step 2 is performed by the Manager. If the Manager approves, the workflow is routed to the Accounts Payable group for final processing.
  • Step 3 is performed by the first person in the Accounts Payable group to click the perform icon on their Task List for this workflow.

Step 1 has a Section named Manager and a section named Accounts Payable. The Visible property on both these sections is unchecked so they are hidden by default.  You want to hide the Manager and Accounts Payable sections for the first step, show the Manager Approval section when the second step is performed by a manager and show the Manager Approval and Accounting sections when the third step is performed by an Accounting department employee.

These two rules will show the Manager Approval section on both the Manager and Accounts Payable step. Note the use of the When current step is on or after Manager condition.

These two rules show the section named Accounts Payable only if the workflow is on the Accounts Payable step. It should not be visible when the workflow is on the steps performed by the employee or the manager.

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. In this if-else statement, notice the use of the special frevvo function "frevvo.step.on()". The value in parenthesis is the step's GUID. 

Rule Code
var event = form.load;
if (frevvo.step.on('_4jCkoKeQEeumO8tqYAdRDQ')) {
  Manager.expanded = true;
  Manager.required = true;
  Manager.enabled = true;
} else {
  Manager.expanded = false;
  Manager.required = false;
  Manager.enabled = false;
}

It can be a little tricky to find the step's GUID if you are writing a rule in JavaScript from scratch. One option is the start the rule in the VRB (to get the GUID) and then switch to Rule Code to finish it. Another is the use built-in data and a variable so you can specify the step name rather than GUID.

Rule Code
var event = form.load;
var an = _data.getParameter("flow.activity.name");
if (an === "Manager") {
  Manager.expanded = true;
  Manager.required = true;
  Manager.enabled = true;
} else {
  Manager.expanded = false;
  Manager.required = false;
  Manager.enabled = false;
}

Control Property Rules

Business rules can be used to dynamically set many control properties. See the Accessing Control Properties chapter for a list of properties that can be set via rules. Here are few common examples.

Printable

Business rules often are used to control what is printed to the final form PDF. This ensures only the data you want is printed, and can help keep the PDF snapshot as simple and easy to read as possible. This form has a radio control named DescribeInDetail and a section control named Details. The Details section is hidden by default and made visible if the user selects 'Yes'.

When the form is submitted we've configured frevvo to send an email with the form PDF. We only want the Details section to appear on the PDF when the user selects 'Yes'. In design mode, uncheck the printable property on the section control. This property will apply to the section and all controls inside the section, so you do not have to uncheck printable on the inner controls. Then create this business rule with the Visual Rule Builder. When the section is visible we also set it to be printable. When the section is hidden we also set it to be not printable.

How it works

 Click to learn how it works...

Click Rule Code to view the Javascript set by the Visual Rule Builder. This is a straightforward if-else statement utilizing the frevvo .printable property.

Rule Code
var event = form.load;
if (DescribeInDetail.value === 'Yes') {
  Details.visible = true;
  Details.printable = true;
} else {
  Details.visible = false;
  Details.printable = false;
}

Enable/Disable Submit and Continue Buttons

A great feature of frevvo is the fact that a form cannot be submitted or a workflow cannot be continued to the next step until all required fields are filled and all filled fields have valid data (e.g. a date field must contain a valid date). Sometimes it might not be as obvious to the form/workflow user why the form/workflow will not submit or continue to the next step. frevvo provides a built-in feature to show validation errors at the time of submission. Refer to the Invalid Form Notification for Users  topic to see how it works.

Enable/Disable a Control

There are many times you may want to conditionally enable or disable controls in your form at run time. Let's say you have a form with two controls named Attending and Presenter respectively. Attending is a checkbox with a single option, Yes. If checked, you wish to ask the addition question, Presenter. 

Use the Rule Builder to create this rule. This rule will automatically fire whenever the user checks or unchecks Attending and will enable/disable Presenter. In this example, you would typically set the checkbox Attending to be initially unchecked and the radio control Presenter to be initially disabled.

Condition Wizard

Be sure to slide the toggle icon to enter the literal value Yes on the Condition wizard.


Rule List


How it works

 Click to learn how it works...

Click Rule Code to view the Javascript set by the Visual Rule Builder. Notice the special built-in method "frevvo.multiValueEquals" which takes two parameters (array, value). Since checkbox values are arrays, this looks at the array to see if it contains the specified value. Even though this particular checkbox only has one option, the checkox control type's value will always be an array. See this documentation and the examples below for more info on writing rules for selection controls.

Rule Code
var event = form.load;
if (frevvo.multiValueEquals(Attending.value, 'Yes')) {
  Presenter.enabled = true;
} else {
  Presenter.enabled = false;
}

Set Valid/Invalid Property

If a control has a pattern or a built-in type (like email, phone or date), it will automatically show as valid when the correct value format is entered, and invalid if an incorrect value is entered. However, you can also control validity dynamically at run time using a business rule. 

This example shows a control named NetWorth, and a rule that checks the value of NetWorth. If NetWorth is less than 0, the rule displays an error message and sets NetWorth to invalid, which also prevents the form from being submitted. When a rule sets the invalid property for a <control>, the background is highlighted with a color (configurable), the error message displays, and the form will not submit just as if the user had entered an invalid value into a phone control. This is a good way to dynamically control your form's valid state. Refer to the Invalid Form Notification for Users for the frevvo built-in method to prevent the submission of forms/workflows with invalid data.

Rule List

How it works

 Click to learn how it works...

Click Rule Code to view the Javascript set by the Visual Rule Builder. This is a straightforward statement that accesses the NetWorth control's "valid" property, which takes a boolean true/false value.

Rule Code
var event = form.load;
if (NetWorth.value < 0) {
  NetWorth.valid = false;
} else {
  NetWorth.valid = true;
}

Set Error Message

Oftentimes when you are setting a control's valid property by a business rule, you also want to customize the error message. This can be done in the Visual Rule Builder using the "error message to" function or in JavaScript by accessing the control's status property.

Action Wizard

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. Notice that the error message is set by the controls 'status' property.

Rule Code
var event = form.load;
if (NetWorth.value < 0) {
  NetWorth.valid = false;
  NetWorth.status = 'Liabilities exceed Assets. Please correct.';
} else {
  NetWorth.valid = true;
}

Set One or the Other Control to Required

Consider a health insurance policy request form in which Employee election or the Family election is required, but not both. Additionally, if one is selected, you want to clear any value that might be in the other (e.g. if the user selected Employee, then changed their mind and selects Family, you must clear the Employee selection.)

In this example we are using two radio controls in the form; one for “Employee Only” and the other for “Family”. The options available for both controls are Accept and Waive. The user must select either one of the radio control to proceed.

You can initially set both controls to required, then use business rules to set one control to optional when the other is filled, and vice versa. To use the Visual Rule Builder, you would need two rules. In JavaScript rule code, you could combine them if desired.

Rule 1: Set Employee-Only to Optional & Empty if Family is selected. If the user selects family, this rule sets the employee-only radio control to optional and empty. The else action sets the employee-only radio control to required.

Condition Wizard

Action Wizard

Else Action Wizard

Rules List

Rule 2, "Set Family to Optional & Empty if Employee is selected", is similar and is shown in the Rules List below. If the use selects employee-only, this rule sets the family radio control to optional and empty. The else action sets the family radio control to required.

At runtime, both controls are required at first. As soon as one control is filled the other control is set to optional and vice versa. Notice that if you change your selection, the opposite control value is cleared.

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. These are both straightforward if-else statements utilizing the frevvo .required property. Notice that we can clear the value of the opposite control by setting the .value property to null.

Rule 1 Code
var event = form.load;
if (Boolean(Family.value)) {
  EmployeeOnly.required = false;
  EmployeeOnly.value = null;
} else {
  EmployeeOnly.required = true;
}
Rule 2 Code
var event = form.load;
if (Boolean(EmployeeOnly.value)) {
  Family.required = false;
  Family.value = null;
} else {
  Family.required = true;
}

Required Field Status in Accessible Forms

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

You can build forms/workflows in frevvo that meet Section 508 and WCAG 2.0 accessibility standards. Accessible forms/workflows can assist users with visual and motor impairments. When the Accessible property is enabled for a form/workflow, the error, "You can't leave this empty <control name>"  displays if users move ahead from a required field without filling it. The status property for the empty control becomes invalid and sets this special error message. Normally, the status property can be used in a business rule to set (or retrieve) the error message displayed whenever the control's value is invalid. 

For example, let's say a form has a text control named 't', and a message control named "m". If you write a rule to update 'm' with the status of the required/invalid control 't', as shown below, the message control will show the Error Message only when an invalid value is entered. It returns a blank value if the required control was left empty.

Rule Code
if(!t.valid)
  {
    m.value = t.status;
  }


Similarly, this rule will not display the "You can't leave this empty" message for a required control in a form with Accessibility enabled, because that message is not treated as the control's status. However, the following rule will fill the message control with the literal text specified here (which matches the Accessibiliy message) when the required control is left empty, and the Error Message text if it's filled with an invalid value.

Rule Code
if (!t.valid) {
  if (t.value.length === 0) {
    m.value = "You can't leave this empty.";
  } else {
    m.value = t.status;
  }
}

Dynamic Label, Help or Hint

You can set the value of control labels, help and hint dynamically in a rule. For example imagine you have a form that either volunteers or staff might complete. You'll ask which role they have in the Radio control "Role." Then, dynamically set the label, hint and help messages of the "Name" control to customize it for their role. Create this rule using the Rule Builder. Even though the label of the Name control will look different to the user, the entered data is all present in the same control in the submission.


Rule List

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. In this example, the values set are literal values in quotes. Notice that the apostrophes are comments out with a backslash (\) character. This is not strictly necessary in this type of rule since labels, hints and help text do not get saved in the submission document or passed through integrations, but it is a good practice in general if setting control values.

Rule Code
var event = form.load;
if (Role.value === 'Volunteer') {
  Name.label = 'Volunteer Name';
  Name.help = 'Enter Volunteer\'s Last Name, First Name';
  Name.hint = 'This field is for the Volunteer\'s Full Name';
} else {
  Name.label = 'Staff Name';
  Name.help = 'Enter Staff\'s Last Name, First Name';
  Name.hint = 'This field is for the Staff\'s Full Name';
}

Expand/Collapse Section

Another useful control property to access dynamically is the Section control's expand/collapse feature. Collapsing sections that are not actively in use reduces clutter in your form and makes it easier for the user to navigate, while still allowing them to expand and see info in the section if they need it.

This example form has three sections. The first section is expanded and the 2nd and 3rd are collapsed. When the user fills in the 1st section they click a "Next" trigger control which causes that section to collapse and the next section to expand. The trigger controls are named next1 and next2. And the sections are named: step1, step2, step3. Use the Rule Builder to create these rules. You will have to create 2 separate rules - one for Step 1 and one for Step2.

Rule List

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. This is straightforward if statement that accesses the trigger control's special property 'clicked' and the section control's 'expanded' property which takes a boolean value of 'true' or 'false'.

Rule Code
var event = form.load;
if (Next1.clicked) {
  Step2.expanded = true;
  Step1.expanded = false;
}

Tab Selection

One unique thing about Tab controls is that you can dynamically design which tab is "selected", or shown, to the user. These rules explain how to use this feature.

Select Tab

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

This rule makes a specific tab the selected tab based on the choice of a radio control. The radio is named SelectTab and has three options: Person, Auto, Home. The tabs are named personTab, autoTab and homeTab. Tabs also can be selected based on trigger controls or other input controls using the same method show here. 

Rule Code
if (SelectTab.value.length > 0)
{ 
    autoTab.selected = false; 
    homeTab.selected = false; 
    personTab.selected = false;

    if (SelectTab.value === 'Auto') {
        autoTab.selected = true; 
    } else if (SelectTab.value === 'Home') {
        homeTab.selected = true;
    } else {
        personTab.selected = true;
    }
}

Next Tab

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

This form contains a trigger control at the bottom of each tab labeled "Next". When "Next" is clicked the trigger rule executes and makes the next tab the selected tab. This assists the user in navigating through the form. The Tabs are named T1, T2, T3, T4. The trigger controls are named C1, C2, C3

Rule Code
// Navigate Tabs 
if (C1.clicked) { 
    T2.selected = true; 
} else if (C2.clicked) {
    T3.selected = true; 
} else if (C3.clicked) { 
    T4.selected = true; 
} 

Pattern

In most cases, the Pattern property can be set directly in the form designer's control properties panel. However, consider a case where you have an existing workflow with pending tasks that contains a control with no pattern set on the first step. The data in the in-flight flows may or may not be consistent with the pattern. If you edit the production workflow to set a pattern on the control, that control could become invalid on in-flight workflow instances that are on later steps and can't be edited. This will prevent those in-flight tasks from being submitted. In this case, you can follow the Best Practices for Updating Workflows in Production and use a business rule to set the pattern on this control only when the workflow is on the first step. This rule will enforce the pattern on all new workflow interviews but will not break in-flight workflows.

You might also use this method when a control's pattern has an either/or scenario. In this example, the control should be valid if four numerical digits are entered, or if the word "NONE" is entered in any letter case, e.g. "none" or  "None".


var event = form.load;
var uc = SSN.value;
var res = uc.toUpperCase(); //change text to uppercase to simplify value comparison

if (frevvo.step.on('_72odfp6qEeuqr9Bz_J-qDw')){ //if the current step is Step 1

  if (res === 'NONE'){
    SSN.valid = true;
  } else if (res !== 'NONE'){
    var pattern = /^[0-9]{4}$/g;
    SSN.valid=uc.match(pattern)?true:false;
  }
}

How it works

The Pattern property is not directly accessible by business rules. However, you can set the desired pattern in a variable and use the JavaScript match method with the conditional operator '?' to compare the control's value to the desired pattern. Set the control's valid property to the result of the match condition, which is true if the variables match and false if they do not match. Be sure to set a meaningful Error Message, which will appear whenever the valid property is false and prompt the user to enter a valid value.

Formatting Rules

There are several cases where you may want to format the data entered into your form in a particular way, such as money or number formatting. You may also wish to set specific patterns on fields dynamically using a business rule based on run-time conditions. The examples in this section will help you customize your data's format.

Format Money Values to Display in a Message Control

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

Let's say you have Number control in your form and you want to display it in a Message control formatted as a money value with commas and decimal places. Add a Number control named Num and a message control named Message to your form. Add a rule and edit the rule code, pasting this rule into the code box. This rule will display the number entered in the number control with commas. If the user enters 5600.44 in the number field then the result in the message control would show "$5,600.44".

This rule uses variables to take the value of Num, convert it to a string, split it at the decimal, and add a comma every third digit from the right of the decimal. It then sets the message value to concatenate the dollar sign, the number with commas added, and the decimal.

Rule Code
	var x, x1, x2;
if (Num.value > 0) {
    var nStr = Num.value.toFixed(2);
    nStr += '';
    x = nStr.split('.');
    x1 = x[0];
    x2 = x.length > 1 ? '.' + x[1] : '';
    var rgx = /(\d+)(\d{3})/;
    while (rgx.test(x1)) {
 x1 = x1.replace(rgx, '$1' + ',' + '$2');
    }
    Message.value = '$' + x1 + x2;
}

Format Money in Text Controls

This rule is not yet supported in the Visual Rule Builder and thus still requires some JavaScript.

You may want to format money with currency signs, commas, decimals and rounded to two decimal places. This example uses a text control for input and a business rule to format the money value.


This rule declares variables and defines the functions numberWithCommas and formatMoney. numberWithCommas converts the number to a string and adds commas every third digit from the right. formatMoney uses the JavaScript Math object to round the number to two decimal places. The last five lines of this rule take the Amount value, strips special characers the user might have entered, and runs these two functions on them. Then it sets Amount value to concatenate the dollar sign and the newly formatted money value.

Rule Code
var x, x1, x2;

var numberWithCommas = function(x) {
  return x.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
};
var formatMoney = function(amt) {
  var decimalAmount = Math.round(amt * 100) / 100;
  return numberWithCommas(decimalAmount.toFixed(2));

};
if (Amount.value.length > 0) {
    var m = Amount.value.replace(/\$/g,"").replace(/,/g, "");
    var formattedMoney = formatMoney(m);
    Amount.value = '$' + formattedMoney;  
}


Here is another example showing a text control named "Money" in a table. Another text control named "Total" displays the column total.

Note the addition of the for loop which runs this rule on each row of the table.

Rule Code
var x, x1, x2;

var tot = 0;
var numberWithCommas = function(x) {
  return x.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
};
var formatMoney = function(amt) {
  var decimalAmount = Math.round(amt * 100) / 100;
  return numberWithCommas(decimalAmount.toFixed(2));

};

if (Money.value.length > 0) {
  for (var i = 0; i < Money.value.length; i++) {
    var m = Money[i].value.replace(/\$/g,"").replace(/,/g, "");
    var formattedMoney = formatMoney(m);
    Money[i].value = '$' + formattedMoney;
    tot = tot + Number(m);
  }
  var formattedTotal = formatMoney(tot);
  Total.value = '$' + formattedTotal;
}

European Number Format

This rule is not yet supported in the Visual Rule Builder and thus still requires some JavaScript.

You may need to display numbers in a locale-specific format. While current versions of frevvo do not support javascript locale methods on number controls, you can write a business rule to handle displaying numbers in your desired format. This example displays a number with a period as the thousands separator and a comma as the decimal separator, i.e. 10.000,00. You can modify this rule slightly for other formats, such as using a space as the thousands separator. This example has a text control in the form named EuropeanFormat.


Rule Code
//use a decimal as thousand separator
var numberWithDecimals = function(x) {
  return x.replace(/\B(?=(\d{3})+(?!\d))/g, ".");
};

//format with two decimals
var formatNumber = function(amt) {
  var decimalAmount = Math.round(amt * 100) / 100; // this adds a decimal with two zeros after the number.
  return numberWithDecimals(decimalAmount.toFixed(2));
};

if (Boolean(EuropeanFormat.value) && Boolean(EuropeanFormat.value)) {
  var e =  parseInt(EuropeanFormat.value.replace(/,/g, ''), 10); 
  var f = formatNumber(e); //format the value using above functions
  var intIndex = f.lastIndexOf(".");
  f = f.slice(0, intIndex) + f.slice(intIndex).replace(".", ",");//change the last decimal to a comma
  EuropeanFormat.value = f;
}

This rule is similar to the format money rule above, in that it adds a decimal with two zeroes behind the number entered, so 12345 displays as 12.345,00. If you'd rather convert the number to a decimal as entered, simply remove the '* 100' from the Math.round() method parameters. This change will display 12345 as 123,45.


TextArea Max Length

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

The TextArea control does not have a maxlength property like the text control does, because in html there is no way to set a maxLength on a TextArea control. However, it is possible to do this via a business rule. This example form has a TextArea control named 'Desc' where the user can enter up to a 500 character description. On this control we also set the ErrorMsg property to the string 'You must limit your description to 500 characters'. This message is automatically displayed when the description control is set to invalid by the following business rule.

Rule Code
if (Desc.value.length > 500) {
  Desc.valid = false; 
} else {
  Desc.valid = true; 
} 

You can even customize the error message by adding this line to your rule. Now the error message will tell the user how many characters they are over the maximum allowed.

Desc.status = 'Invalid. Max 500 chars allowed and you have ' + Desc.value.length; 

Convert TextArea newline to HTML break

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

Users may enter multi-line text into TextArea controls. If you want to display that text in an html context, for example on a web page, in an html formatted email, or in your form's Form Action display message you will need to replace newlines with html breaks. Line breaks entered into a web form TextArea are represented by a single newline character \n while line breaks in an html context are represented by the html break characters.

Our example has a TextArea control named Description and a hidden text control named DF. The user types into the visible control named Description and a business rules converts the newline characters (\n) into html breaks (<br/>), and sets the new value in the hidden control 'DF'. Note that this particular rule also replace the carriage return (\r) with a blank. You will then use the template {DF} in your message control, form action, email, etc.

var x = Description.value; 
x = x.replace(/\\r/g,""); // replaces "Carriage Return" (CR, ASCII character 13) with a blank
x = x.replace(/\\n/g,"<br/>"); // replaces "Line Feed" (LF, ASCII character 10) with an html line break
DF.value = x; 

TextArea Wrap Long URL in PDF Snapshot

This rule is not yet supported in the Visual Rule Builder so still requires some Javascript.

If users enter a long URL into a TextArea control, it appears wrapped in use mode but does not wrap in the PDF snapshot. Here is a rule to ensure text wraps in the PDF snapshot if needed.

Rule Code
var str;
if (form.unload) {
str = Source.value; //Source is the name of Text Area where user enters the URL.

var result = '';
while (str.length > 0) {
result += str.substring(0, 20) + '\n'; //The 2nd number '20' is the number of characters per line. Adjust this based on the width of your TextArea control.
str = str.substring(20); //See note above
}

Source.value = result;
}

Split Phone Number

There may be cases where you collect data from the user in one format, such as a phone number, but you need to use it in another format, such as in two different fields on a mapped PDF. You can use standard JavaScript methods to accomplish this. Here is an example that uses split() and also strips the separators (- or .) from the resulting values. You can use a similar method to split emails or other text as well.

Rule Code
var p = PhoneNumber.value;

if (PhoneNumber.value.includes('-')){
  var split = p.split("-");

  AreaCode.value = split[0];
  Number.value = split[1] + split[2];
}else if (PhoneNumber.value.includes('.')){
  var split = p.split(".");
    
  AreaCode.value = split[0];
  Number.value = split[1] + split[2];

} else {
  AreaCode.value = p.substring(0, 3);
  Number.value = p.substring(3,10);
}

The result places the split values in two separate controls at run time. These controls would typically be hidden in use mode and mapped to the PDF.

Prefilling Rules

Initializing a form with data is a popular way to streamline data entry for your users, declutter forms (prefilled controls can be hidden) and reduce potential errors. Many of these rules optimize built-in methods to retrieve data stored in frevvo, such as user info, tenant info, and form info.

Tenants, Roles, and Users

frevvo has several built-in methods that enable you to access information about your current tenant. Some common examples are:

  • Initialize a form with the logged in user data (first name, email address etc).
  • Populate fields with user data for another user
  • Populate a dropdown with a list of users and roles.
  • Display a list of users with a specific role
  • Display a list of users with multiple selected roles

Use the Rule Builder to Initialize a form with user data - the Rule Builder has built-in functions for user information. Use the Dynamic Options feature to populate a ComboBox with a list of users and roles - no JavaScript required.

Displaying lists of roles for selected users and populating Dropdowns with lists of users/roles still require JavaScript using frevvo built-in methods. Some of these methods return a Boolean true/false value. Others return a JSON string that is automatically converted to a JavaScript object.

This section contains several examples to get you started.

Initialize Form with Current User Info

Prefilling form controls with the logged-in user's info can save your user time and prevent data entry errors. Use the Rule Builder functions userID(), user FirstName(), userLastname(), userFullName(), userEmail(), and userManagerID() to create this rule. When the form loads, fields are populated with the logged-in user information.

Condition Wizard

You don't strictly need a condition for this rule in a form. However, if you are using a workflow, you will want to set a condition to run the rule on the particular step you want to gather user info, or set a condition like "When userID is empty" so that the rule does not run again on subsequent steps that may have different users.

Action Wizard

Rule List


How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. Notice the use of the frevvo built-in methods for the "subject", or current logged-in user.

Rule Code
var event = form.load;
UserID.value = _data.getParameter('subject.id');
FirstName.value = _data.getParameter('subject.first.name');
LastName.value = _data.getParameter('subject.last.name');
FullName.value = _data.getParameter('subject.first.name') + ' ' + _data.getParameter('subject.last.name');
EMail.value = _data.getParameter('subject.email');
ManagerID.value = _data.getParameter('subject.reports.to');

Populate Form with Any User's Info

Perhaps you want to prefill form fields not with the logged-in user's info, but with another user's info. This might be used in a case where you get the logged-in user's manager's userID, and then you want to look up the manager's email using their userID. In this example, a user id is entered into a text control in the form named UserLookup. When the user enters a frevvo user id into the UserLookup field, the uFirstName, uLastName, uFullName, uEmail and uManagerID are populated with the information about that user.


Condition Wizard

Action Wizard

The user functions in the VRB take the parameter userId. In this case, the userId is in the control 'UserLookup', so you enter that control name in each function's parentheses.

Rule List

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. This examples uses the variable user_UserLookup to get the user details using the built-in metho userDetails for the user ID entered in the UserLookup control. Then, each control value is set to the specific userDetail property, i.e. firstName, lastName, etc. The VRB uses the Boolean check in the if condition, but this is not strictly necessary.

Rule Code
/*members firstName, lastName, reportsTo, email */
var user_UserLookup;
var event = form.load;
if (Boolean(UserLookup.value)) {
  user_UserLookup = frevvo.userDetails(UserLookup.value);
  uFirstName.value = user_UserLookup.firstName;
  uLastName.value = user_UserLookup.lastName;
  uFullName.value = user_UserLookup.firstName + ' ' + user_UserLookup.lastName;
  uEmail.value = user_UserLookup.email;
  uManagerID.value = user_UserLookup.reportsTo;
}

The userDetail function can also be used to retrieve individual information fields for the currently logged in user. These fields can either be one of the standard fields or a custom attribute configured using the LDAP Security Manager.
The standard properties are 'id', 'first.name', 'last.name', 'email' and 'reports.to'.

Populate Dropdown with Users/Roles

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

Populating the options of a ComboBox control with lists of users/roles can be done without writing JavaScript rules. See Dynamic Options feature to populate a ComboBox for details.

Perhaps you want users to be able to select a user or role from a list of all the users or roles in your tenant. This might be used to set up dynamic workflow step assignments or to get user info for a specific user. This example populates the following controls when the form loads:

  • text controls with the name of the current tenant and the logged in user
  • a dropdown named AllUsers with a list of all users in the current tenant
  • a dropdown named AllRoles with a list of all roles in the current tenant

Leave the default options for the dropdown controls in the designer.

Rule Code
if(form.load){
currentTenant.value = frevvo.currentTenant();
currentUser.value = frevvo.currentUser();
AllUsers.options = frevvo.userIds();
AllRoles.options = frevvo.roles();
}

Populate Dropdown with Roles Assigned to a User

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

Similar to the example above, you can access of list of all the roles assigned to a particular user. In this example we use that list to populate a dropdown control, so the user can select a role at runtime.

In the code below, we have set the rule to get the roles for the user 'designer'. You could replace "designer" (in line 3) with the <controlname>.value where a userID is entered or populated to make this rule dynamic.

Rule Code
var event = form.load;
var options=[];
var ud = frevvo.userDetails("designer"); 
var roles = ud.roles;
for (var i=0; i < roles.length; i++) {
  options[i] = roles[i] + '=' + roles[i];
}
Roles.options = options;

List Users in a Role

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

A common requirement is to filter the list of users in a tenant to display only users that have a specified role. The frevvo.userIds() and frevvo.roles() functions can be used in a rule to accomplish this.

One approach is to populate one dropdown control with all the roles in your tenant, allow the user to choose a role and then display the results in a dropdown. Another approach is to use an invisible text field where you hardcode the role name. Remember that frevvo role names are case-sensitive.

Let's say you want to display a list of users that have the Manager role in a dropdown named Role. The user sees only the users that are assigned the Manager role instead of the entire list of users in the tenant. Once a user is selected from the filtered list you can display the details about that user.

Here is an example of a rule that filters the list of users to only those that are assigned the Manager role and populates the options of a dropdown control with the results. The frevvo.userDetails(String userId) function is used to retrieve the details about the selected user (Jim). The results are displayed in a formatted Message Control named m. The form has a text field named Role with an initial value of "Manager".  This field is referenced in the rule to supply the role name.

Rule Code
/*member email, firstName, id, lastName, reportsTo*/

if(form.load){
UsersWithManagerRole.options = frevvo.userIds(Role.value); //Populate dropdown with users who have the role entered in the 'Role' control.
}

//Display the user details for the selected user
var ud = frevvo.userDetails(UsersWithManagerRole.value); 

m2.value = "<b>Selected User Details :</b><br/>"+
 "User ID : "+ud.id+"<br/>"+
 "User FirstName : "+ud.firstName+"<br/>"+
 "User LastName : "+ud.lastName+"<br/>"+
 "User FullName : "+ud.name+"<br/>"+
 "User Email : "+ud.email+"<br/>"+
 "User ReportsTo : "+ud.reportsTo+"<br/>";

List Users in Multiple Roles

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

You can also select more than one role from your tenant list and use a business rule to display a filtered list of users who are assigned any of the selected roles. This business rule populates the options for a checkbox named Roles with the list of all users in the tenant. Selecting more than one role from the list populates a dropdown named UsersWithSelectedRoles with the filtered list of users assigned those roles. Details for the selected user are displayed in a formatted Message Control named m.

Rule Code
/*member email, firstName, id, lastName, reportsTo*/
if(form.load){
Roles.options = frevvo.roles(); //Populate Checkbox options with all roles in the tenant 
}

UsersWithSelectedRoles.options = frevvo.userIds(Roles.value); //Populate dropdown with users who have any of the roles selected in the Roles checkbox

//Display the user details for the selected user
var ud = frevvo.userDetails(UsersWithSelectedRoles.value);
m.value = "<b>Selected User Details :</b><br/>"+
 "User ID : "+ud.id+"<br/>"+
 "User FirstName : "+ud.firstName+"<br/>"+
 "User LastName : "+ud.lastName+"<br/>"+
 "User FullName : "+ud.name+"<br/>"+
 "User Email : "+ud.email+"<br/>"+
 "User ReportsTo : "+ud.reportsTo+"<br/>";

List a User's Roles

It's also possible to list all of the roles assigned to a specified user. This rule gets the user's roles using the same built-in methods we used above to initialize the form with the logged-in user's info. If you were to set them in a text or textArea control, you could simply have added a line to that rule which returns the list of roles.

RolesText.value = _data.getParameter ("subject.roles");

To populate the roles in a dropdown, use a variable ('roles' in this example) to hold the string of roles and evaluate it to an array, which can then be used as the dropdown options.

Rule Code
var x;
if (form.load) { 
	// Get the User's Roles and set them as dropdown options
    var roles = _data.getParameter ("subject.roles"); 
    if (roles) { 
        eval ('x=' + roles); 
        Roles.options = x; 
    } 
}

Verify User

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

This rule executes when the user enters a value into the username text field named 'U'. It uses the built-in isUniqueUserId() method that returns false if the user already exists. If the user already exists this rule then sets the value of a message control, makes that message control visible on the form and sets the Username valid property to false so that Username field displays as invalid to guide the user to make a correction. Notice that the isUniqueUserId() method takes two parameters, userId and tenant name. In this example, we have set the tenant name in a control 'tenant'. You could also hard code this or set it dynamically using the frevvo.currentTenant(); method.

See the section on dynamic content for more details.

Rule Code
if (U.value.length > 0) {  
    if (frevvo.isUniqueUserId(U.value, tenant.value) === false) { 
        M.value = 'User: ' + U.value + ' already exists'; 
        M.visible = true; 
        U.valid = false; 
    } else { 
        M.visible = false; 
    } 
} 

Verify Role

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

This rule executes if there is a value in a field named role. It uses the built-in isUniqueRoleId() method that returns false if the role already exists. If the role already exists, this rule displays the message "The role <role entered> already exists in the tenant <tenant name>." to notify the user. Notice that the isUniqueRoleId() method takes two parameters, userId and tenant name. In this example, we have set the tenant name in a control 'tenant'. You could also hard code this or set it dynamically using the frevvo.currentTenant(); method.

Rule Code
// Verify that a role already exists in the tenant
if(role.value.length > 0)
{
  t.value = frevvo.isUniqueRoleId(role.value, tenant.value);
  if (frevvo.isUniqueRoleId(role.value, tenant.value) === false) {
    ErrMsg.value = 'The role ' + role.value + ' already exists in tenant ' + tenant.value; 
  }
}

Unique and/or Sequential ID

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

Forms such as invoices, bills of lading, or purchase orders often need to be stamped with a unique ID. There are several different approaches you could take for this business requirement. 

  1. Use the frevvo Database Connector (or another Web Service) to create a sequential unique ID for each submission. See this example in our Database Connector documentation.
  2. Use the frevvo Google Connector the create sequential numbers. This approach is described in the Google Connector documentation on this page, however it has some limitations. One is that you must guarantee that only one person at a time is filling out your form. This is because there is no mutex around the read and update of the Google spreadsheet cell. 
  3. If the unique ID does not need to be sequential, you can use the form id generated by frevvo. The _data 'form.id' is guaranteed to be unique for every new form instance. Capture the form id using _date.getParameter as follows:

    Rule Code: Unique ID using form UUID
    if (form.load) 
    { 
        InvoiceNum.value = _data.getParameter('form.id'); 
    } 
  4. An another approach is create a number from a timestamp using the JavaScript Date method as follows. new Date() creates a date object for the exact millisecond the rule runs. Then valueOf() returns the primitive value of that object, and toString() converts it to a string. If it's unlikely you will have multiple forms initialized at the same second, this will very likely provide unique numbers.

    Rule Code: Unique ID using JS Date()
    // some VERY likely unique number
    var event = form.load;
    if (!(PONumber.value)) {
    var n = new Date().valueOf().toString();
    PONumber.value = n;
    }

Signatures

frevvo offers built-in, legally binding signatures for authenticated users. However, there may be times when you want to create your own signature stamp using an external source, pin code, or other such method to authenticate. You may also want to work with the Signature control from palette (anonymous signature) to give it a similar behavior in UI such as setting a date stamp after signing. The following examples demonstrate rules for such scenarios.

Signature via Web Service

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript. 

This form uses a rule to pass a username and password to an LDAP Active Directory authentication service. If authentication fails the form makes an error message control visible. If authentication succeeds the form disables the username form field and replaces the password field with a date field set to the current date. The form contains a trigger control named sign, username and password fields named u and p respectively, a date field named d and a message field named m.

Rule Code
/*member auth */
var x;
 
if (sign.clicked) { 
    // passwords may contain characters that need url encoding 
    var p_encode = encodeURIComponent(p.value);

    eval('x=' + http.get('http://(your webhost)/authServices/signForm?username=' + 
                          u.value + '&password=' + p_encode));

    if (x.auth) { 
        var dt = new Date(); 
        var day = dt.getDate(); 
        var month = dt.getMonth() + 1; 
        var year = dt.getFullYear(); 
        d.value = month + '-' + day + '-' + year;

        d.visible = true; 
        u.enabled = false; 
        p.visible = false; 
        sign.visible = false; 
        m.visible = false; 
    } else { 
    m.visible = true; 
    } 
}

The authService is an example HTTP servlet that returns a JSON response.

public void doGet (HttpServletRequest request, HttpServletResponse response) 
    throws ServletException, IOException {
 
    try { 
        String username = request.getParameter(REQUEST_SIG_USERNAME); 
        String password = request.getParameter(REQUEST_SIG_PASSWORD); 
        password = URLDecoder.decode(password, "UTF-8"); 
        // Authenticate Signature 
        authenticateUser(response, username, password);  
    } catch (Exception e) { 
        throw new ServletException(e); 
    } 
}

private void authenticateUser(HttpServletResponse response, String u, String p) { 
    if (realm.authenticate(u, p) === null) 
        response.addHeader(RESPONSE_JSON_HEADER, "{auth:false}"); 
    else 
        response.addHeader(RESPONSE_JSON_HEADER, "{auth:true}"); 
} 

Here's another example form that requires a doctor's signature. This shows how the form works in use mode. The first image contains a dropdown to select one of the doctor's authorized to sign the form and a text control where they enter their PIN code.

This image shows the case where the doctor entered an invalid PIN and the error message becomes visible.

This image shows the case of a valid PIN. Today's date is entered into the date control via the rule and made visible and disabled from edit. The username dropdown is disabled and the PIN and Sign controls are hidden.

Set Signed Date

This example sets a date control to today's date as soon as the user signs the form. The Signature control is named EmployeeSignature and the date control is named EmployeeSignDate.

Use the today() function in the Rule Builder to create this rule.

Condition Wizard

Action Wizard

Else Action Wizard

Rule List

How it works

 Click to learn how it works...

Click Rule Code to view the JavaScript set by the Visual Rule Builder. Notice the use of the built-in method frevvo.currentDate(), which returns the current date in the user's local time zone.

Rule Code
var event = form.load;
if (Boolean(EmployeeSignature.value)) {
  EmployeeSignDate.value = frevvo.currentDate();
} else {
  EmployeeSignDate.value = null;
}

Enable Click to Sign for Anonymous User

Perhaps you would like your anonymous user to be able to "click to sign" that automatically enters a text signature (similar to the way the authenticated-user signed section works). You can do this using a checkbox control and two business rules.

First, add the Click Here to Sign checkbox control. Then, add a business rule that enables that checkbox only if all other sections are valid (meaning, required controls have been filled in):

Rule Code
if (Section1.valid === true && Section2.valid === true){
  ClickHereToSign.enabled = true;
  ClickHereToSign.required = true;
} else {
  ClickHereToSign.enabled = false;
  ClickHereToSign.required = false;
}

Finally, use the Visual Rule Builder to concatenate the First Name and Last Name the user entered at run-time.

Rule List

At run time the result looks like this:

Doc Action, Activity Doc Action, and Precondition Related Rules

Conditionally Send Email

Let's say you have a form or workflow step that should send an email only under certain conditions. The solution is to dynamically fill a control with either the recipient's email address (when the condition is true) or a no-reply type email address (when the condition is false.) In the example below, the Account Receivable form will only send an email to the Client Services Manager if the payment is related to a services project. 

  1. To dynamically send an email, add a hidden email control (SendtoCSEmail) to your form.
  2. In the Email Doc Action (or Email step for a mid-workflow Activity Doc Action), enter the control name as a template in the "To" field.



  3. Use the Visual Rule Builder to fill the hidden email control with the valid email if the condition is true, and a no-reply email if the condition is false. The Else Action is important here - if you set it to Empty or to an invalid string (any string not using the syntax <name>@<name>.<string>), you will get a submission error.


    You can also set the hidden email to a template, as shown below, or to the userEmail() function, so that it is evaluated at run time.

  4. When the user clicks Submit or Continue, the email will send to either the valid email (condition=true) or the noreply email (condition=false.)

Construct Form URL

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript. A rule can dynamically construct the URL to itself. This can be handy when you want to add a link to your form's URL to an email message or to the form action display message. In this example FormURL is the name of a text control in your form.

Rule Code
if(form.load){
  var baseUrl = _data.getParameter('_frevvo_base_url') + 
      "frevvo/web/tn/" +
      _data.getParameter('tn.id') +
      "/user/"+_data.getParameter('user.id') +
      "/app/"+_data.getParameter('app.id') +
      "/formtype/"+_data.getParameter('form.type.id') + "?_method=post&embed=true"; 
  FormURL.value = baseUrl;  
}

For workflows, replace Line 8 above with "/flowtype/"+_data.getParameter('flow.type.id') + "?_method=post&embed=true";

Now FormURL can be used as a template in your display message as shown below.

Thank You!<br/><br/> 
Your account will be created within 24 hours.<br/> 
Click <a href="{FormURL}">here</a> to request another demo account.

Rules by Control Type

This section will cover example rules for various control types. Some control types have their own properties and methods, which are helpful to understand when using the Visual Rule Builder or Rule Code Editor to customize their behavior. 

Selection Controls | Date and Time Controls | Repeats | Tables | Upload Control | Message Control

Selection Controls

Dropdowns, Checkboxes, Radio, ComboBox and T/F controls are selection controls. You can populate your selection control options, either statically or dynamically, using business rules. You may want such customized picklists for:

  • List of products for a Sales Order / PO
  • Number of available vacation days for a Leave Approval
  • List of projects for a Time Sheet

and many more....

You may want to populate selection control options by pulling from a web service or database. You can do this without writing an JavaScript code with the frevvo Dynamic Options feature.

Options

Set Options

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

Populating options works the same way for all selection controls, by accessing the control's ".options" property. The options must be set in an array, where each value in the array represents an option. The option value is the value passed in the submission .xml document, while the label is what the form user will see. When your option value and label are the same, each array value can simply be the option value. frevvo will automatically use that item as the option label as well. When the option value and label are different, each array item uses the syntax '<option value>=<option label>'.

The simplest method to set the options array is to use an array literal. 

Set Options when Option Value and Label are the SAME
if (form.load) { 
    var cc = ['Red', 'Blue', 'Green'];
    Colors.options = cc;
}
Set Options when Option Value and Label are DIFFERENT
if (form.load) { 
    var cc = ['R=Red', 'B=Blue', 'G=Green'];
    Colors.options = cc;
}

In several examples below you will see other methods to dynamically set the options array.

Set Options to Control Values

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

You may wish to customize your selection control options to the values entered in other form controls at runtime. Unlike other control properties, options do not support templatized strings, so you will have to write a rule to set the options. Let's say you have a form that asks the user to enter three items, and then select their top choice from those three items. You have three text controls (Item1, Item2, and Item3) and a radio control (TopChoice). Write your rule as follows:

Rule Code
var opt = ['I choose ' + Item1.value,'I choose ' + Item2.value, 'I choose ' + Item3.value];

TopChoice.options = opt;

The run time result will look like this:

Default Selection

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript. 

When your options are set dynamically in a business rule, you cannot set a default selection in the form designer. You need to set the default in the rule. If your options have <value>=<label> where value is different from label, make sure you set the <control>.value to '<option value>', not '<label>' nor '<option value>=<option label>'.

Set Options and Default Value
if (form.load) { 
    var cc = ['R=Red', 'B=Blue', 'G=Green'];
    Colors.options = cc;
	Colors.value = 'R';
}

Display Selected Option Label

This rule is not yet available in the Visual Rule Builder, and will require some JavaScript.

One common use for the Dropdown (or Radio) control is to allow the person completing the form to select who will perform the next step from a list of users. In this case, the designer may set up the Dropdown options with the userId as the option value (to ensure a valid user assignment when this field is used as a template in the Assignment tab), but a friendly name, such as the user's first and last name, as the option label. However, since the form user does not know that the value does not equal the label, when they search their tasks or submissions for 'First Name Last Name', they see no results because they should be searching for userId.

You can use this business rule to display the Dropdown's option label in a hidden field, and then set that hidden field as the Searchable Field for users to search task list or submissions by. Here's an example of a dropdown where the options value and label are different. Notice that we have a hidden control beside it to collect the selected option's label:

Create a new rule, click Rule Code, and then Edit Rule Code. Add this code (replacing the control names with your control names.)

Rule Code
var x;
var selectedcolors = '';
 
    var v = AsssignStep2To.value;
    for (x in AsssignStep2To.options) {
 
        var opt = AsssignStep2To.options[x];
        var val= opt.split('=')[0];
        var lab= opt.split('=')[1];
        if (v === val) {
            selectedcolors = selectedcolors + ' ' + lab;
        }
    }
SelectedOptionLabel.value = selectedcolors;

The result is that when an option is selected from the dropdown, we pass the option value in the dropdown control, and the option label in the hidden control. The Selected Option Label control is visible here in use mode for demo purposes:

In the Workflow Settings Searchable Fields tab, select the hidden field (in this example, "Selected Option Label") instead of the dropdown control itself. This allows your users to search by the option label, set in the hidden field, rather than the Dropdown value, which they do not know.

Clear Selections

This sample resets a dropdown option to the automatically added blank option. For dropdowns added from palette controls and from schema, frevvo automatically adds a blank option so the dropdown initially shows no choice by default. To reset the dropdown, set the dropdown control's value to null, not to the empty string. The empty string will not work since the empty string is not a valid option. This form resets the dropdown named size whenever the value of the product option changes. This also works for Radio and Checkbox controls, even though they do not have a built in blank option.

Randomize Options

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

You may want the options of a selection control to appear at random each time a user opens the form, such as in a quiz. Add your selection control and options.

Then, add this rule:

Rule Code
var points = select.options;

if (form.load) {
  points.sort(function(a, b) {
    return 0.5 - Math.random();
  });
}

select.options = points;

Each time you load the form, you will see the options in a different, random order.

The JavaScript method sort() also allows you to show options in alphabetical order, which can be helpful when getting Dynamic Options from database, Google Sheet, or other web service. 

Dynamic Options

The Dynamic Options rules discussed in this section are not yet supported in the Visual Rules Builder and thus still require some JavaScript.

Selection controls' (radios, checkboxes, dropdowns, T/F) options can be set dynamically from a webservice (such as the frevvo Database Connector or Google Connector) via rules. This keeps your forms in sync with your database and ensure the accuracy of your submission data.

frevvo provides a built-in no-code Dynamic Options feature in the form/workflow designer. See this documentation and short video to see how it works. 

Selection Controls from Schema

If the selection control you are populating comes from an XSD schema data source rather than one of the standard palette controls, take care to set the options to values that are valid for that schema element. For example, imagine that your XSD has a string enumeration and lists valid options as 'red', 'green', and 'blue'. If you were to use a rule to dynamically set the options to 'small', 'medium', 'large', your form will not work correctly in use mode. If a user selects the option 'small' they will get a validation error on the form because 'small' is not one of the options allowed by your underlying XSD schema.

Options from a Database

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

This example uses the frevvo Database Connector to set a list products as dropdown options. The option value is the Product Code, which is a rather cryptic number that would not be easy for the user to choose. So, we have set the Product ID as the option value but the user-friendly Product Name as the visible option label.

Rule Code
/*member productName productCode resultSet */
var x, opts;
 
for (var i=0; i < x.resultSet.length; i++) { 
    if (x.resultSet[i]) { 
            opts[i] = x.resultSet[i].productCode+ '=' + x.resultSet[i].productName; 
    } 
} 
Products.options = opts; 

Combobox Options from a Webservice

This rule is not yet supported in the Visual Rules Builder and thus still requires some JavaScript.

In many cases, you can simply use the Dynamic Options feature to pull ComboBox options from a web service in the Form Designer without writing business rules. However, if you need more complex dynamically determined endpoint URLs that cannot be built using control templates within the URL or if you have multiple ComboBoxes making HTTP calls to a web service and notice performance issues, you may choose to use business rules to populate options instead. See ComboBox Control Properties for Business Rules

Limiting Results to Improve Combobox Performance

A Comobobox that pulls options from a webservice might return a large number of options which can slow performance. One way to improve the performance of a Comobobox that pulls options from a web service is to configure your query to limit the results returned. Here is an example of a SELECT statement that limits the results to 50 rows. 

SELECT NAME FROM SUPPLIER WHERE UPPER(NAME) LIKE UPPER('%{NAME}%') AND ROWNUM <= 50 ORDER BY NAME
Example 1 - Set optionsUrl in a business rule.

You must still set the ComboBox OptionsSrc property to Webservice and set the Bind Path in the Properties panel. This is a very simple example of setting the optionsUrl property in a business rule. Notice the use of the built-in JavaScript method encodeURIComponent, which encodes the ComboBox value entered at run time in case it may have spaces or special characters.

Rule Code
ComboBox.optionsUrl = 'http://localhost:8082/database/combobox/productsByName?pname=' + encodeURIComponent(ComboBox.matchText);
Example 2 - Populate options directly from webservice.
/*member productCode, productName, resultSet*/

if (ComboBox.matchText) {
var x;

eval('x=' + http.get('http://localhost:8082/database/combobox/productsByName?pname=' + encodeURIComponent(ComboBox.matchText)));
var opts = [];
var j = 0;

for (var i=0; i < x.resultSet.length; i++) {
if (x.resultSet[i].productName.includes(ComboBox.value)) {
opts[j] = x.resultSet[i].productName;
j++;
}
}
ComboBox.matchingOptions = opts;
}
Example 3 - Populate Options from JSON

This method is useful when you have multiple ComboBoxes and making multiple calls to the same webservice impacts performance. This simple example gets product data from the Database Connector and stores it in a hidden textArea in the form. Then a second rule parses the data and sets the ComboBox options. Please see the chapter on Reusing Dynamic Content for more details.

Rule 1 Store Results in Hidden Control
if (form.load) {
  JSONData.value = http.get('http://localhost:8082/database/combobox/allproductsByName');
}
Rule 2 Populate Options
/*member productName, resultSet*/
if (ComboBox.matchText) {
  var opts = [];
  var j = 0;
  var x = JSON.parse(JSONData.value);
  for (var i = 0; i < x.resultSet.length; i++) {
      if (x.resultSet[i] && x.resultSet[i].productName.includes(ComboBox.value)) {
        opts[j] = x.resultSet[i].productName;
        j++;
      }
    }
  ComboBox.matchingOptions = opts;
}
Example 4 - Populate ComboBox in a Table

Similare to Example 3, this reuses content stored in a hidden text control in your form. However, it provides additional code to loop through the table when setting options.

//Populate ComboBox options using results saved in the TextArea
/*member DESCRIPTION, resultSet*/
for(var k=0;k<Combobox.value.length; k++){
  if (Combobox[k].value.length > 0 && Combobox[k].matchText) {
    var x = JSON.parse(jsonUserData.value); 
    var opts = [];
    var j = 0;
    for (var i = 0; i < x.resultSet.length; i++) {
      if (x.resultSet[i] && x.resultSet[i].DESCRIPTION.includes(Combobox[k].value)) {
        opts[j] = x.resultSet[i].DESCRIPTION;
        j++;
      }
    }
    Combobox[k].matchingOptions = opts; 
  }
}

Options from a Google Sheet