Handle events

📘
Note
Optimizely Forms is only supported by MVC-based websites and HTML5-compliant browsers.

Query client-side events

The following JavaScript code shows how to handle client-side epiforms events in Alloy MVC templates.

if (typeof $$epiforms !== 'undefined') 
  {
    $$epiforms(document).ready(function myfunction() 
      {
        console.log('listen to event');
        $$epiforms(".EPiServerForms").on("formsNavigationNextStep
                                          formsNavigationPrevStep
                                          formsSetupCompleted
                                          formsReset
                                          formsStartSubmitting
                                          formsSubmitted
                                          formsSubmittedError
                                          formsNavigateToStep
                                          formsStepValidating",
                                          function (event, param1, param2)
          {
            console.log($$epiforms(this).get(0), event);
          });
      });
  }

For a QuickSilver site, put the following script before @Html.RequiredClientResources("Footer").

if (typeof $$epiforms !== 'undefined')
  {
    console.log('listen to event');
    $$epiforms(".EPiServerForms").on("formsLoadExternalScripts formsLoadExternalCss", function (event, param1, param2)
      {
        console.log($$epiforms(this).get(0), event);
      });
  }

The following jQuery event objects are notification-only:

type – Type of event.
workingFormDOMElement – The DOM element raises the event.
workingFormInfo – Contains meta-information of current Optimizely Forms.
formData – some submitting-related events, this property contains the standard FormData object of the submission.

📘
Note
The form event handling script must be placed below the @Html.RequiredClientResources("Header"). For example:

<head>
    @Html.RequiredClientResources("Header")
    @Scripts.Render("/ClientResources/Scripts/FormEventHandling.js")
</head>

📘
Note
If event handling script is rendered using EPiServer.Framework.Web.Resources.IRequiredClientResourceList, then it must depend on EPiServer.Forms.ConstantsForms.StaticResource.JS.FormsjQuery and EPiServer.Forms.ConstantsForms.StaticResource.JS.EPiServerFormsPrerequisite. For example:

var requiredResources = ServiceLocator.Current.GetInstance<IRequiredClientResourceList>();
requiredResources.RequireScript("/ClientResources/Scripts/FormEventHandling.js", "", new List<string>{
    ConstantsForms.StaticResource.JS.FormsjQuery,
    ConstantsForms.StaticResource.JS.EPiServerFormsPrerequisite
}).AtHeader();

.NET events

Form submissions (and form step submissions) must result in events.

FormsStructureChange
FormsStepSubmitted
FormsSubmissionFinalized
FormsSubmitting

The following example code catches server-side events in InitializationModule:

// get the Forms Event Manager to listen to its events
var formsEvents = ServiceLocator.Current.GetInstance<FormsEvents>();
formsEvents.FormsStructureChange += OnStructureChange;
formsEvents.FormsSubmitting += OnSubmitting1;
formsEvents.FormsSubmitting += OnSubmitting2;
formsEvents.FormsStepSubmitted += OnStepSubmit;
formsEvents.FormsSubmissionFinalized += OnFormFinalized;

With FormsSubmitting, FormsStepSubmitted, and FormsSubmissionFinalized events, you can cast the eventArgs to FormsSubmittingEventArgs, where you can get information from SubmissionData (having SubmissionData.Data as IDictionary<string, object>) and the FormSubmissionId.

List of events

formsNavigationNextStep
formsNavigationPrevStep
formsSetupCompleted
formsReset
formsStartSubmitting
formsSubmitted
formsSubmittedError
formsNavigateToStep
formsStepValidating
FormsStructureChange
FormsStepSubmitted
FormsSubmissionFinalized
FormsSubmitting