formData.on

Registers handlers for the default app logic events of a form driven flow. These events include predefined moments in the flow execution sequence, such as before the form's user interface is initially rendered, after a step's data is saved to the database, or advancing to the next step of a form. For more information about the default client-side app logic events, see the code execution sequence documentation.

The method's first argument determines the event the handler is attached to:

Event triggered before the form's user interface is rendered for the first time. The event is triggered once per flow per mode (insert/edit). This means that, for an insert flow, the event may trigger twice: at the flow's start and when transitioning from insert to edit mode (typically when the user clicks Next for the first time to advance from the first step to the second step).

Copy 
formData.on("formBeforeGenerate", handler: () => void): IDisposable;

Event triggered every time after a step is rendered for the first time, before the stepAfterLoad event. The event is triggered once per flow per step per mode (insert/edit). This means that, for an insert flow, the event may be triggered twice on the same step, e.g.: when the first step is in insert mode at the flow's start and when revisiting the first step for the first time after the form has transitioned into edit mode (returning via the Previous button).

Copy 
formData.on("formAfterGenerate", handler: () => void): IDisposable;

Event triggered every time before the form data is saved to the database (e.g.: when clicking Next or Finish, but not when clicking Previous) and before the step's stepBeforeSave event.

Copy 
formData.on("formBeforeSave", handler: (context: IBeforeSaveContext) => void): IDisposable;

You can set the canSave property of the context event object to false to abort the save and trigger only the navigation. E.g.:

Copy 
formData.on("formBeforeSave", function(context){
    if(!condition){
        context.canSave = false;
    }
});

Alternatively, you can set the skipSave property of the context event object to true for the same purpose. E.g.:

Copy 
formData.on("formBeforeSave", function(context){
    if(!condition){
        context.skipSave = true;
    }
});

This is an alias for formBeforeSave.

Event triggered after a specific step's user interface is rendered for the first time and after formAfterGenerate. The event is triggered once per flow per step per mode (insert/edit). This means that, for an insert flow, if a step is rendered for the first time when the flow is in the insert mode, then revisited after the flow has transitioned to the edit mode (e.g. by navigating back in the flow using the Previous button), the stepAfterLoad event will trigger twice.

Copy 
formData.on("stepAfterLoad", stepName: string, handler: () => void): IDisposable;

Event triggered before a specified step's data is saved to the database (e.g.: when you advance to the next step or, if it's the final step in the flow, when you click the Finish button).

Copy 
formData.on("stepBeforeSave", stepName: string, handler: (context: IWizardBeforeSaveContext) => void): IDisposable;

You can use the canSave property of the context event object to abort the save. E.g.:

Copy 
formData.on("stepBeforeSave", "Step2", function(context){
    if(!condition){
        context.canSave = false;
    }
});

Event triggered after a specified step's data is saved to the database (e.g.: when you advance to the next step or, if it's the final step in the flow, when you click the Finish button).

Copy 
formData.on("stepAfterSave", stepName: string, handler: (context: IWizardAfterSaveContext) => void): IDisposable;

The context event object is an object of type IWizardAfterSaveContext:

Copy 
interface IWizardAfterSaveContext {
  sections: Array<IWizardSection>;
  goToSection(sectionIndex: number): void;
  navigateUrl: string;
  stopNextNavigation: boolean;
}

Event triggered every time a step is displayed, after the step's user interface is rendered (and before formAfterGenerate if triggered). The method supports two signatures:

  • For a specific step:
    Copy
    formData.on("stepNavigation", stepName: string, handler: () => void): IDisposable;
  • A generic signature applicable to every step of the flow:
    Copy
    formData.on("stepNavigation", handler: (formName: string, stepName: string) => void): IDisposable;

When using the generic signature, the callback function supports automatic parameter injection, receiving the formName and stepName arguments directly from the stepNavigation event. These parameters represent the name of the form and the name of the step, respectively, and you can use them in the callback function to implement logic specific to the current form and step.

You can define multiple handlers for the same event by storing the formData.on definitions in variables. This way, when an event is triggered, all its handlers' callback functions are executed.

Copy 
formScope.firstHandler = formData.on('formBeforeGenerate', firstFunction);
formScope.secondHandler = formData.on('formBeforeGenerate', secondFunction);
formScope.thirdHandler = formData.on('formBeforeGenerate', thirdFunction);

The formData.on methods return an IDisposable object that enables you to remove such event handlers using the dispose() method:

Copy 
formScope.firstHandler.dispose();
formScope.secondHandler.dispose();
formScope.thirdHandler.dispose();

Examples

Copy 
formScope.myChangeSection = formData.on("stepNavigation", function(formName, stepName){
    console.log("changeSection", formName, stepName, formData, formScope);
});
Copy 
formScope.myChangeSection.dispose()