Pre-submission actions

By default, actions run when the form is submitted. When building a rule, a the default run time is 'User submits the form'.

Form Builder supports an alternative run time, which is User reaches the end of the form. If this is selected when building a rule, the choice of actions to fire will change to be those that are defined as pre-submission.

It is not possible to fire pre-submission actions from a rule that runs on form submission. Equally, on submission actions cannot be fired before submission. However, it is possible to create multiple rules, where some run before submission, and some run on submission.

Building a custom pre-submission action

Pre-submission actions are built in the same way as any other (custom action)[actions.md].

Once you have completed your action, you'll need to make a few changes to support pre-submission run time.

Firstly, your action class needs to implement the IRunOnReviewAction interface. You can see an example of this from the PayBridge MakePaymentActionType.

use Jadu\XFormsPro\Form\Rules\Actions\IRunOnReviewAction;
use Jadu\XFormsPro\Form\Rules\Actions\ProgressMappedActionType;

class MakePaymentActionType extends ProgressMappedActionType implements IRunOnReviewAction
{

Next, you'll need to make sure your class implements the following methods in order to satisfy the interface:

    /**
     * Should return any HTML that should be displayed on the form, before the action runs.
     *
     * @return string
     */
    public function getDisplayableContent() {}

    /**
     * Should return the text for the review page submit button, if this differs to 'Submit Form'.
     *
     * @return string
     */
    public function getReviewButtonText() {}

    /**
     * Should return true if the action has completed.
     *
     * @param UserForm $userForm
     *
     * @return bool
     */
    public function hasRanSuccessfully(UserForm $userForm);

getDisplayableContent should return some HTML, which will be placed on the review page instead of the usual text asking the user to submit the form. Any pre-submission action that returns anything other than an empty string from getDisplayableContent is categorised as 'Interactive'. This means Jadu Central will expect this action to change the flow through the form, as require user interaction. When creating an interactive action, getReviewButtonText should be used to return some text to replace 'Submit Form' on the Review page's action button.

If getDisplayableContent returns an empty string, Jadu Central will run the action silently, and the Review page will be unchanged.

Finally hasRanSuccessfully(UserForm $userForm) should be implemented, to ensure that the action does not run and submit data multiple times. If this returns true, the action will not re-run. If it returns false, the action will be ran again.