Dev GuideAPI ReferenceUser Guide
HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

Note

Episerver Forms is supported by MVC-based websites only.

Changes to Forms include separating the Forms add-on into three smaller packages that follow the CMS code structure: _EPiServer.Forms.Core_ (referred to as _Core_), _EPiServer.Forms.UI_ (referred to as _UI_), and _EPiServer.Forms_ (referred to as _Forms_).

  • The Core package exposes all back-end code composed of the core interfaces and classes, which can be overridden and extended by third parties.

  • The UI package contains the classes and typical resources for a web project, such as modules-content, config, or an installation script. This package is used to render the edit mode.

  • The Forms package, which depends on the other ones, comprises the resources needed to render the ViewMode.

This separation lets third-party developers simplify and shorten the installation process of the NuGet packages and remove unused components for their purposes. For example, if you want to customize form elements, just install the Core and UI package so that the web-related Forms components are not included in a project; this shortens installation time and makes the code structure simpler and smaller in size. The following breaking changes are described in this topic in greater detail.

  • The utility functions of add-ons development were moved to a new project named _EPiServer.AddOns.Helpers_ (referred to as _Helpers_). There are two main purposes for doing this.

    • The Helpers is beneficial to the new add-on development.

    • The separation helps to avoid the breaking changes in the Forms add-on and other ones in case some major changes for utility functions are required to fit new requirements.

  • Episerver changed the signature of important methods in interfaces or classes to make them simpler and more generic. Episerver added more functions to interfaces or base classes to satisfy extension requirements proposed by clients who had used previous versions of the Forms add-on. Episerver changed portions of the `FormsExtension` class. The extension methods of generic class types (such as `Object`) now become the static methods of the class, while the ones for specific class types are mostly kept the same.

## EPiServer.Form.Core

### Main components:

The Core package now is a standalone NuGet package (DLL library and configuration only) and contains the following interfaces and base classes.

  • Events

  • Data

  • FormRepository

  • Abstraction of Configuration

    • Settings in DDS

  • Internal

    • Feed API

    • Autofill API (BETA)

    • ExternalSystem API (BETA)

    • VisitorIdentity API (BETA)

    • PlaceholderService

  • Models

  • Autofill

  • External System (Field mapping)

  • Event (server side events, Form Structure event and Form Structure Handler)

  • Validation

  • `VisitorData` and `VisitorDataService`

  • Actor

    • `ActorsExecutingService`

    • `IPostSubmissionActor` and `IPostSubmissionActorModel`

  • Constants

### API changes regarding the Core package.

  • `EPiServer.Forms`. Describes classes moved to UI project under this namespace.

    • `Constants`. The class defines the constants for the project

  • `EPiServer.Forms.Core`. Describes classes moved to UI project under this namespace.

    • `IUIEntityInEditView`. Defines UI entity of forms.

    • `IExcludeInSubmission`. Used to exclude the data submission.

    • `DependCondition`. Represents a dependent condition type.

  • `EPiServer.Forms.Core.Validation`. Describes those classes moved to UI project under this namespace or the one nested within it.

    • `IElementValidatable`. Defines properties and methods for the self-validation of form elements. Its new namespace is `EPiServer.Forms.Core.Validation`.

    • `ValidatorInfo` and `ValidationDescriptor `classes are used to represent the validator information of a form element. Their new namespace is `EPiServer.Forms.Core.Validation.Internal`.

    • `RegularExpressionValidationModel` and `RegularExpressionValidatorBase `classes: they define the base validation model for form elements. Their new namespace is `EPiServer.Forms.Core.Validation.Internal`.

    • `IValidationService `interface defines functions required for the data validation service.

    • `IElementValidator` interface and the class `ElementValidatorBase` respectively define and implement the function to build the validation model for form elements.

  • `EPiServer.Forms.Core.Internal`. Describes those classes moved to UI project under this namespace.

    • The class `JsonObjectConverter`. Defines the methods for reading and writing Json data.

    • The class `DataSubmissionService`. Performs data submissions from users at the client side.

    • The class `FormBusinessService`. Calculates the next step to be displayed. We extract the function `GetAllDependee` from the class `FormsExtension` and add it to this class.

    • The class `ProgressiveSubmitInfoService`. Stores and retrieves the progressive submit information. By default, the information is stored in browsers’ cookies.

    • `PlaceHolder`. An internal DTO object for replacing text holder with actual value.

    • `PlaceholderService`. Replaces placeholders such as `#summary#` with real values.

  • `EPiServer.Forms.Core.Data`. Describes those classes moved to UI project under this namespace.

  • `IFormDataRepository`.

    Two data storage-related new features let administrators set up read-only mode, and lets users choose whether the form data submission is stored through the **Allow to store data submission** property. Episerver added methods to the interface that let you return the right type of data storage services to clients in different contexts.

    The new code also lets clients pass a submission storage for data operations, facilitating the need of form customization from clients.

  • `EPiServer.Forms.Helpers.Internal`. Describes those classes moved to UI project under this namespace.

    • `FormsExtensions` class. Contains the extension methods to retrieve and process data of forms and elements. Some methods of this class are moved to another one.

      • `GetCommonMessages` and `GetFormExternalResources` are moved to `FormContainerBlockController`.

      • `GetFieldsExcludedInSubmissionSummary`, `RenderTextWithEmptyPlaceHolders`, and `RenderTextWithPlaceHolders` are moved to the class `FormParagraphTextService`.

      • `HasAccessRightToReadFormData` is moved to `Addon.Helper`.

      • `GetSubmittableStatus` is changed to `GetFormSubmittableStatus` and moved to `SubmitButtonElementBlock`.

    • `CaptchaGenerator`. Generates images containing random text string.

    • `ModuleHelper`. Provides the functions for mapping paths and the host environment.

    • `EPiServer.Forms.Configuration`. Describes those classes moved to UI project under this namespace.

      • `Settings` class. Contains the global settings of `EpiForms`. The property `VisitorGroupProperties` is removed from the class `Settings`. That property of the class `BuiltinVisitorDataSourceConfig` should be enough.

## Forms.UI

### Main components

The UI package provides widgets, REST stores and services for Forms add-on in EditView; it contains the following main components.

  • ShellModule

    • Dojo client resources for EditView widget

  • Annotation

  • EditView

    • Classes just for EditView and for serving Dojo widgets

    • Part of UI for manipulating forms in EditView.

    • Store

    • FormModuleModel

    • EditorDescriptors

    • CustomProperties

    • SelectionFactory

  • Important base classes

    • BlockBase

    • ElementBlockBase

  • ViewEngine

    • Razor

    • WebForms

  • Actors implementation and its custom properties

    • WebhookActor

    • SendEmailActor

### API changes.

  • `EPiServer.Forms.EditView`. Describes those classes moved to UI project under this namespace.

    • `IFeedConfig`. Exposes properties for the configuration of external feeds.

    • `IEPiServerFormsUIConfig`. Exposes properties for the configuration of Forms UI.

    • `FormsWebFormViewEngine`. Its namespace is changed to `EPiServer.Forms.EditView`.

    • `FormsRazorViewEngine`. Its namespace is changed to `EPiServer.Forms.EditView`.

    • `ConstantsFormsUI`. Contains constant values of the UI project.

    • `PropertyGenericList` class. Displays the user interfaces for configuring complex form elements such as `ImageChoice`, `Validator`, and so on. in EditView.

    • `ICustomViewLocation` interface and `CustomViewLocationBase` class. Sets up the default view location of Forms and Forms.Samples add-on.

    • `IElementHasFeedItems` interface. Defines the information required for a form element to have data as a feed of items.

  • `EPiServer.Forms.EditView.Internal`. Describes those classes moved to UI project under this namespace.

    • `ValidationService` class. Implements functions used for the form elements validation. Within this class, we add two more functions to extract the validator information of a form element.

      • `GetValidatorTypesIncludedForAnElementType`. Returns a list of validators used for a form element.

      • `GetValidatorTypesExcludedForAnElementType`. Returns a list of validators not used for a form element.

    • `ExternalFieldMappingService` class. Retrieves the information about external fields mapping to Forms and Form elements.

    • `DefaultFeedProvider` class. Provides the default type of an XML Feed and loads feeds from configuration.

    • `FeedService` class. Accesses the Feeds and pre-configure the feed of items. Its new namespace is `EPiServer.Forms.EditView.Internal`.

    • `OAuthXmlFeed` class. Takes items from a XMLstring, enable the authentication fulfilling by OAuth, and fetch data from a remote URL.

    • `XmlFeed` class. Takes items from a `XmlString` and fetch data from the remote URL.

    • `FormStructureHandler`. Exposes API to handle changes regarding the Form structure.

  • `EPiServer.Forms.EditView.Controllers`. Describes the controllers moved to UI project under this namespace. Those ones only are used in EditMode, therefore, they should be placed within the UI project.

    • `FormControllerBase` class. The base class for MVC controllers using the forms add-on.

    • `DataExportingController` class. Exports data and related functions.

    • `FormDataStore` class. Retrieves the information and data of forms and form elements.

    • `ExternalFeedStore` class. Retrieves the information of external data sources. Its new namespace is `EPiServer.Forms.EditView.Controllers`.

    • `FormsElementStore` class. Retrieves the form element information, is moved to UI project.

    • `VisitorDataSourceStore` class. Retrieves visitor data.

  • `EPiServer.Forms.EditView.DataTransfer`. Describes those classes moved to UI project under this namespace.

    • `DataExporterBase` class. The base class for all data exporters. It defines the signature for the functions to export data in different formats.

    • `CSVDataExporter`. Exports data and CDV format. (Default)

    • `JSONDataExporter`. Exports data in Json format.

    • `XMLDataExporter`. Exports data in XML format.

  • `EPiServer.Forms.EditView.Models.Internal`. Describes those classes moved to UI project under this namespace.

    • `IOptionItem` interface and `OptionItem` class. Represents an item of a selection element.

    • `StepDescriptor` class. Serializes the step information.

    • `ChartPeriodicity` class. Draws the chart only in EditView.

  • `EPiServer.Forms.EditView.DataAnnotations`. Describes those classes moved to UI project under this namespace.

    • `AvailableValidatorTypesAttribute` class. Defines validators for a specific form element to add to the project.

    • `LocalizedDisplayNameAttribute` class. Localizes the display name of a specific property.

  • `EPiServer.Forms.Implementation`. Describes those classes moved to UI project under this namespace or the one nested within it. Although the following classes belong to UI project, the namespace `EPiServer.Forms.Implementation` remains to prevent so many changes in code for Episerver clients.

    • `FormStepBlock` class. Defines the main properties of a step.

    • Built-in WebHook: Changes the format of Json data sent by this built-in to make `CallWebHookAfterSubmissionActor` more compatible with other systems in data transferring.

      • The Json data now is a single JSON object, not an JSON array any more.

        Example:

        
## Forms
### Main components
This should be the default working web solution. With this package installed, an Editor can create a form immediately without the need of software development. Forms package depends on Core and UI using NuGet dependency. For this package, we still keep its name as _EPiServer.Forms_. People who install _EPiServer.Forms_ will have the same result as Forms 2.0; an all-in-one working solution for Editor and Administrator of their sites. The main components of this package are listed below.
  • Implementation of Configuration (in file) and Settings
  • Fundamental ElementBlocks (Text, TextArea, SubmitButton, captcha, and so on.)
  • ASCX View
  • CAPTCHA Generator
  • Validators
  • Actors executing mechanism
  • Data repositories
  • Data exporters (XML, JSON, CSV)
  • ClientResourceRegister
  • Built-in VisitorDataSource (to silently collect data from visitor)
  • Geo
  • Profile
  • UserAgent
  • VisitorGroup
  • Built-in CoreController, and the custom route to this built-in controller
### API changes.
  • Changed the module using geo-location data providers to extract the user information and save into the database.
  • The current default geographical database, _Freegeo_, is replaced by _Maxmind Geo-ip_, which is bundled with _EpiServer.Personalization dll_. Episerver clients still can use the _FreeGeo_ datasource as their default data provider by adding the following lines to the geo-location section of _web.config_ and set `freegeo` as `defaultProvider`.

  • New exposed API lets you choose different geo-location data providers for his site. 
  • Create a new geo-location provider class that inherits `EPiServer.Personalization.GeolocationProviderBase` and `EPiServer.Forms.Implementation.Providers.GeolocationProviders.ICustomGeolocationProvider`.
  • Create a `GeoDataProcessService` that inherits `EPiServer.Forms.Internal.GeoDataProcessService.IGeoDataProcessService`.
  • Configure the new provider in _web.config_ by adding the following line to geo-location section and `set defaultProvider=”ProviderName”` and then, add the following line:

  • Added a new `FormParagraphTextService` class that replaces a placeholder with `FormElement`'s value.
  • Added a new `GetFormSubmittableStatus` method to the `SubmitButtonElementBlock` class. For a given form element, this method checks whether its form container can be submitted.
  • `PlaceHolderManager` is marked as Obsolete.
  • `SubmissionSummaryElementBlockBase` is marked as Obsolete. (`IExcludeInSubmission` should be enough.)
  • The namespace of `IViewModeExternalResources` is changed to `EPiServer.Forms.Implementation`.
  • The namespace of `FormStep` and `FormContainerBlock` is still kept as `EPiServer.Forms.Implementation.Elements.`