Page tree
Skip to end of metadata
Go to start of metadata

Purpose

Runtime Value Calculation is the tool to use when the value a form field/component should be dynamically calculated based on the value of another form field/component.

For example, if you wanted to have:

  • A field called "full-name",
  • That was dynamically calculated from the user-provided fields of:
    •  "first-name" and
    • "last-name"

You could use Runtime Value Calculation along with some JavaScript in order to achieve this.

Whenever the user changed their input for "first-name" or "last-name", the value of "full-name" would be recalculated.

Runtime Value Calculation can also use data from your website environment, such as the URL the user is visiting or their logged-in username. See User and Page Data to learn more.

Applies toText Field, Text Area Field, Rich Text Editor, Choice Field (Radio Field, Select Field, Checkbox field), Date Field, Time Field, Hidden Field.

Types of Runtime Value Calculation

SmartForms currently supports two kinds of Runtime Value Calculation: JavaScript and Webservices.

JavaScript

JavaScript enables you to calculate field values based upon code that you can write.

SmartForms JavaScript supports all of ECMAScript 5/5.1 with partial support for later versions - it is best to stick to simple language features. Please also keep in mind that there are strict limits on the amount of memory and execution time for any code you run.

Returning a Value

SmartForms expects the code to return a value, as you would in an ordinary JavaScript function. The simplest example of this is:

return "my-field-value";

The type of value you return needs to match the field type you are applying the Runtime Value Calculation to:

SmartForms Form Component TypeExpected Type of Value Returned in JavaScriptExample Value
TEXTString
// Strip all of the spaces from phone number
var phoneNumber = $fields[phone-number]
return phoneNumber.replace(/\s/g, '');
INTEGER or FLOATNumber
// Return the price of the drink based on the selected size
switch ($field[drink.size]) {
  case 'SMALL':
    return 4.99;
  case 'LARGE':
    return 7.99;
  default:
    return 0;
}
DATE

Date object.

The Date must comply with the Date Range Limits (if present) on the date field.

// Return the current date plus a number of days into the future as defined by the "days-to-add" field
var d = new Date();
d.setDate(d.getDate() + $field[days-to-add]);
return d;
TIME

String in 24-hour "HH:MM" format.

The value must comply with the Granularity setting of the field.

// Return the current hour at zero minutes
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
var d = new Date();
return d.getHours() + ":00";

For choice fields (radio, select and checkbox), the calculated value MUST be one of the configured choices on the field.

Accessing Other Field Values

There is a special syntax for accessing other field values.

// To access a form field called 'field-name', use the expression;
var value = $field[field-name];

// To access the value of a website environment parameter, called 'param-name' use the expression:
var value = $portal[param-name];


Take care not to create fields that depend on each other. This will cause one of the fields not to be calculated.

Webservices

SmartForms can invoke a remote webservice to ask what the value of a field should be. See Using Webservices to Populate Form Data section for more details on how to setup this option.

This option is available for advanced use cases. If you can, use JavaScript, as it will be simpler and faster!

How To Use Runtime Value Calculation

You assign runtime value calculation in the Runtime Value Calculation Editor in the Visual Designer. See Assigning Input Field Values to learn how to open the Editor.

Triggering Runtime Value Calculation without Depending on Other Fields

Usually, Runtime Value Calculation will only happen when a field depends on another field. However, sometimes you may need the field to be recalculated all of the time. For example, to record what time that particular form page was opened.

The Recalculate on Page Load setting enables you to set up Runtime Value without any dependency on other components. It forces recalculation of the runtime value whenever the page where this component is located gets reloaded, for example when user selects this page or clicks Next or Previous button to arrive on the page.

  • No labels