Skip to main content

Using Fast Formula to personalize forms

The Form block and the Flexible block support personalized forms using Fast Formula. They are defined in the block's settings and are typically called the View personalization formula or Edit personalization formula.

The View formula on the Flexible block is a different kind of formula with different options. Please refer to the Flexible documentation for details on using this formula.

Using Fast Formula to personalization forms is optional. You might use a Fast Formula in the following use-cases:

  • You're using a seeded Applaud form and wish to override specific field properties (you are not permitted to change seeded forms)
  • Setting whether a field is visible or not using complex conditions that would be too difficult to write in a simple hideIf expression.
  • Setting other field properties based on a condition
  • Setting field properties based on the results of a database query (via a Fast Formula function)
  • Setting field properties based on the user's run-time context
  • Setting field properties you could only know at run-time, not at design time

In some cases, using Fast Formula is not needed. For example, if you're using your Form and want to permanently change a field's property, such as its label or whether it's enabled or not, you could change the value in the Form builder rather than in Fast Formula.

Personalization formula essentials

All personalization formulas follow the same structure. The Fast Formula is called when initially building the Form and on each subsequent refreshOnChange event.

These are the essentials:

  • All form fields have an Id. You can retrieve any existing form field property in the Fast Formula by defining a Fast Formula Input with the pattern {field_id}_{property_name}_in. For example, Person_Id_Value_In, or First_Name_Visible_in. All Inputs must have Default for statements. You can then use these inputs to write conditions in your formula.
  • You can set any form field property in Fast Formula by returning an Output using the output name {field_id}_{property_name}, for example, Person_Id_Value or First_Name_Visible. Any Form field properties you set, you must include in the Return statement. Otherwise, they're ignored (unless you have set them via xxas_emp_set_long_output).
  • The fast formula has an in-build variable restriction of 150 characters. If you are trying to set a form field property that may exceed that limit, you should use the Fast Formula Function xxas_emp_set_long_output to set larger values. Please see the Formula Function's definition for expected parameters. When setting via this method, you do not need to include the output in the Return statement.
  • The fast formula doesn't support NULL values. See Handling null values in the formula.

Example formula

Here is a simple example of a personalized Fast Formula. This formula hides the Last Name field if the First Name is John:

Default for First_Name_Value_in is 'Unknown'

Inputs are First_Name_Value_in

If First_Name_Value_in = 'John' Then
  (Last_Name_Visible = 'false')
  
Return Last_Name_Visible

In this example, the Form would have to include a field with an Id of FIRST_NAME and a field with an Id of LAST_NAME for this condition to work.

This would only work when the Form is first loaded and not when a user changes their First Name. A further refinement to this formula could be as follows:

Default for First_Name_Value_in is 'Unknown'

Inputs are First_Name_Value_in

First_Name_Refresh_on_Change = 'true'

If First_Name_Value_in = 'John' Then
  (Last_Name_Visible = 'false')
  
Return Last_Name_Visible
      ,First_Name_Refresh_on_Change

The First Name field has its refreshOnChange property set to true in this refinement. This would mean that when a user changes the value of their First Name to John, it would re-run the Fast Formula and hide the Last Name field.

A final refinement is to hide the field using a javascript expression automatically:


Last_Name_Hide_If = 'model.FIRST_NAME.value !== ''John'''

Return Last_Name_Hide_If

This example uses a hideIf expression rather than a refreshOnChange event. This means the Fast Formula is not re-run each time the user changes their First Name, and the field is immediately hidden in the app without a round-trip to the server. This is a faster and better user experience for this use case.

Javascript hideIf expressions can only be used to toggle the visibility of a field. To set other properties dynamically, such as a label or whether a field is required or not, one would need to use a refreshOnChange event.

Handling null values in the formula

When defining a Fast Formula, you specify Defaults for all inputs. For dates, this is often 01 Jan 0001. For numbers, it is often 0. For strings, it is often Unknown or a space (' '). A NULL value might be displayed as its default rather than nothing at all, for example, the app may show 01 Jan 1 (for dates) or 0 (for numbers) because Fast Formula does not support NULL values. That is, you cannot set a date, character, or number to NULL.

The app has a feature that works around this restriction. You can set a value to null by setting its value to one of the following special constants:

  • Character fields: XXASNULLVAL
  • Numbers: -987123654
  • Dates: 4712-01-01 00:00:00

If you set these values in the Fast Formula, the app will automatically convert to show no values in the display.

Another alternative technique is to hide the field altogether. This can be achieved using the was defaulted keyword in Fast Formula. For example:

if national_identifier was not defaulted then
     National_Identifier_Visible = 'false'
end if

Sections in this article