User Inputs & Forms

Many types of calculations require input from users. For example, a user might want to override the list price in a quote. And a dashboard may let the user filter transactional data by a time interval. In these cases, you need to program a form logic that builds these inputs.

Form logics are sometimes referred to as configurators.

Generating Inputs

End-users are sometimes able to provide their inputs to various calculations. For example, end-users can provide inputs to dashboards, price lists, quotes — but not to workflows. If user inputs are available, the logic will at some point execute in a special mode, called input generation mode. This execution results in the generation of objects that the frontend application uses to render input fields. When the user has provided values for those input fields and chooses to run the calculation, the logic will execute in regular mode and perform the business logic.

The special execution mode that generates the inputs was formerly called Syntax Sheck mode. This name has been changed in Pricefx version 10.0, but you can still encounter it in older projects.

When a logic is generating the user input fields, the logic does not yet have access to the values of those input fields. Since the results wouldn’t be meaningful, you do not want to execute the code that performs the business logic. There is a special function that allows you to detect whether the logic is currently being executed in input generation mode (api.isInputGenerationExecution()), and another to skip the execution of subsequent elements (api.abortCalculation()).

To keep things simple, adhere to the separation of concerns design principle: let the business logic delegate the input generation to a dedicated form logic (more on this in the next section).

In each logic, always let the first element script contain a single call to the Form.build() method:

libs.Library_Input.Forms.build()

Where the Form.build() is defined as:

https://github.com/pricefx/example-configuration/tree/main/pricefxSrc/CalculationLogic/Library_Input/elements/Forms

void build(String formLogicName = null, String label = 'End-user Input') {
    if(!api.syntaxCheck){
        return
    }

    if(formLogicName){
        api.inputBuilderFactory()
                .createConfiguratorInputBuilder('_user_inputs', formLogicName, true)
                .setLabel(label)
                .getInput()
    }

    api.abortCalculation()
}

This will ensure that your business logic is not executed in input generation mode.

Then, if you want to generate inputs, create a so-called form logic (more on this further down) and provide the name of that logic as an argument to Forms.build():

libs.Library_Input.Forms.build('My_Form_Logic')

See the example configuration for an example.

Form Logics

A form logic is a logic with a single responsibility: to build user inputs.

For more details, see the form logic reference.

The form logic scripts should always return a group of inputs — called a form field set:

An empty form field set

Add inputs to the form field set with setInputs():

An empty form field set

And build the inputs with input builders:

Example of how to build a user input with input builders.

You can return multiple form field sets, by wrapping them within a form field set array: