Package net.pricefx.formulaengine.forms

Interface FormActionApi

All Superinterfaces:
FormInputBuilderApi
public interface FormActionApi extends FormInputBuilderApi
The FormActionApi is exposed to form logics through the form binding during the action mode.

This phase is triggered when a user changes the value of an input. The logic can react by updating other inputs (e.g., setting values, labels, read-only state), inserting new inputs, or modifying the layout.

Extends FormInputBuilderApi so that input builder methods (e.g. create*) are available for creating inputs to pass to insertAfter(String, ContextParameter...).

Since:
17.0 - Paloma

  • Method Details

    • sourceInputName

      String sourceInputName()
      Returns the name of the input that triggered the current form execution. This is typically the input whose value changed.

      Example: 

      
     if (form.sourceInputName() == "country") {
         form.updateInput("city").setValue(null)
     }
      Returns:
      The name of the source input.
      Since:
      17.0 - Paloma

    • updateInput

      FormChange updateInput(String inputName)
      Returns a FormChange object for the specified input, allowing modification of its properties such as value, label, read-only state, or validity. If no FormChange exists yet for the given input name, a new one is created. Subsequent calls with the same input name return the same instance.

      Example: 

      
     form.updateInput("total")
         .setValue(input.quantity * input.price)
         .setReadOnly(true)
      Parameters:
      inputName - The name of the input to update. Must not be null.
      Returns:
      A FormChange instance for the specified input.
      Throws:
      NullPointerException - if inputName is null.
      Since:
      17.0 - Paloma

    • insertAfter

      FormChange insertAfter(String inputName, ContextParameter... inputsToAdd)
      Inserts one or more new input definitions after the specified existing input. This allows dynamically adding inputs to the form during custom action (onValueChange, onClick...) mode execution. Multiple calls for the same input name accumulate the inputs to be inserted.

      Example: 

      
     def newInput = form.createStringUserEntry("notes")
         .setLabel("Notes")
         .buildFormInput()

     form.insertAfter("quantity", newInput)
      Parameters:
      inputName - The name of the existing input after which new inputs will be inserted. Must not be null.
      inputsToAdd - The input definitions to insert as ContextParameter instances.
      Returns:
      A FormChange instance for the specified input, with the new inputs queued for insertion.
      Throws:
      NullPointerException - if inputName is null.
      Since:
      17.0 - Paloma

    • recalculateParent

      void recalculateParent()
      Requests a full recalculation of the parent document (Quote, Agreement/Promotion, Rebate Agreement, Compensation Plan) once the frontend applies the changes of this form execution. It is the Forms equivalent of the configurator flag recalculateParentEntityOnConfirm.

      The recalculation runs the same way as when the user clicks Recalculate. It is requested by this execution only, so the logic calls the method again whenever another change needs it. It has no effect when the form is not attached to a document header or line item. When recalculateParentChanges() is called in the same execution as well, the full recalculation wins.

      The action phase runs only for the inputs registering a value change or click event, e.g. with onValueChange().

      Example: 

      
     if (form.sourceInputName() == "Currency") {
         form.recalculateParent()
     }
      Since:
      18.0 - Painkiller

    • recalculateParentChanges

      void recalculateParentChanges()
      Requests a recalculation of the changes of the parent document (Quote, Agreement/Promotion, Rebate Agreement, Compensation Plan) once the frontend applies the changes of this form execution, that is only the changed line items are recalculated, the same way as when the user clicks Recalculate Changes.

      It is requested by this execution only and has no effect when the form is not attached to a document header or line item. When recalculateParent() is called in the same execution as well, the full recalculation wins.

      Example: 

      
     if (form.sourceInputName() == "Plant") {
         form.recalculateParentChanges()
     }
      Since:
      18.0 - Painkiller