Where to integrate with Episerver Forms

If you want to control what’s going on when a form created with Episerver Forms is submited, there are different areas you can implement your logic. The most usable ones (or the ones most people would go for) would be Controllers where the submitted form is posted, the implementation of DataSubmissionService, various Events and through Actors.

So which one should you use? It all depends on what you want to do and here are my thoughts on where to integrate depending on what you want to do.

So what are these?

First we’ll do a quick check on the different areas I mentioned.

lifecycle

Controllers

First of all, Episerver Forms use two Controllers that receive data from the posted forms.

DataSubmitController

This one is called with the out of the box Javascript-driven functionality that makes an AJAX request with the form data. This requires the visitor’s browser to be able to use Javascript.

To replace this controller, the easiest way would be to change the path with coreController configuration in \modules\_protected\EPiServer.Forms\Forms.config.

There are some other ways but that would require that you create your own Javascript-functionality for the form, which would require that you create your own rendering Controller for FormContainerBlock (see below) that does not output the OOTB Javascript references.

FormContainerBlockController

This is if you have turned off the Javascript-support using the workInNonJSMode configuration in \modules\_protected\EPiServer.Forms\Forms.config or if the visitor’s browser does not have Javascript support.

To replace this controller you’ll need to create your own rendering Controller and make sure that it is used instead of the original FormContainerBlockController.

DataSubmissionService

This class is used by the Controllers and takes care of the submitted data, validates and stores it. It is registered into Episerver’s IOC with the usage of EPiServer.Forms.Services.DataSubmissionService.

You can simply replace it by creating a ConfigurableModule. However as it handles quite alot of the nice stuff to interpret the submitted information from the forms, I would recommend to not play around too much here.

Events

As I mentioned in my previous post about Episerver Forms, there are some Events that you can hook up to:

  • FormsSubmitting
    Before each step, at least once
  • FormsStepSubmitted
    After each step, at least once
  • FormsSubmissionFinalized
    When final step is posted
  • FormsStructureChange
    When a Form Container Block is published

Events were the most common way in XForms to take care of the data that was submitted from the form, for example if you want to save or send it somewhere.

Actors

Actors are the ones that do the final actions when submitting the form. They implement the interface IPostSubmissionActor and the built in actors are SendEmailAfterSubmissionActor and CallWebHookAfterSubmissionActor.

The simplest way to create your own Actor is to create a class that inherits PostSubmissionActorBase.

As you’ve seen with the WebHook and E-mail actors, you can also create your own interface to customize the Actor from the editor interface but I don’t have any examples for that right now.

Thanks for the update, but I still don’t know which I should use?

Controllers

Given the various options I would rarely touch the Controllers since they manage both the initiation and rendering of your forms.

If you’re daring enough to replace the overall rendering, for example when it comes to the Javascript based submits, go ahead and create your own FormContainerBlockController.

From a rendering point of view the FormContainerBlock is nothing more than a block that has a Controller with a TemplateDescriptor attribute. These are stored as TemplateModels in the TemplateModelRepository and can be modified there using an InitializationModule.

DataSubmissionService

Here all the nice stuff to interpret the posted data, store files and so on, so I would try to keep this intact.

The only good reason I’ve heard where it would be necessary to replace the DataSubmissionService would be to override where uploaded files are stored.

Events

This is the classic way to read and do something extra with the posted information. It still works, but I would say that if you want to save or send the data at the end station of the cycle, this would not be here.

Here I would recommend that you read or modify the data if needed, but don’t perform any actions based on it.

Actors

This is where the train stops and all Actors that are interested in the data from the form do what they are supposed to do. If you’re going to send extra information to an external service I would suggest you do that here.

Summary

I haven’t worked with Episerver Forms in a live project yet, but at least these are the areas I would suggest you can use. If you have any ideas or more tips, feel free to add a comment below!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: