Forms 3 - Breaking changes
Describes the breaking changes from Optimizely Forms version 2 to version 3.
Note
Optimizely 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 third parties can override and extend.
- 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 others, 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, suppose you want to customize form elements, install the Core and UI package so that the web-related Forms components are not included in a project. In that case, this shortens installation time and makes the code structure simpler and smaller. The following breaking changes are described in this topic in greater detail.
- The utility functions of add-ons development were moved to a project named
EPiServer.AddOns.Helpers
(referred to as Helpers). There are two main purposes for doing this.- The Helpers is beneficial to the add-on development.
- The separation helps to avoid the breaking changes in the Forms add-on and other ones in case major changes for utility functions are required to fit 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 asObject
) 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
andVisitorDataService
- Actor
ActorsExecutingService
IPostSubmissionActor
andIPostSubmissionActorModel
- Constants
API changes regarding the Core package.
-
EPiServer.Forms
. Describes classes moved to the UI project under this namespace.Constants
. The class defines the constants for the project
-
EPiServer.Forms.Core
. Describes classes moved to the 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 the 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 isEPiServer.Forms.Core.Validation
.ValidatorInfo
andValidationDescriptor
classes are used to represent the validator information of a form element. Their new namespace isEPiServer.Forms.Core.Validation.Internal
.RegularExpressionValidationModel
andRegularExpressionValidatorBase
classes: they define the base validation model for form elements. Their new namespace isEPiServer.Forms.Core.Validation.Internal
.IValidationService
interface defines functions required for the data validation service.IElementValidator
interface and the classElementValidatorBase
respectively define and implement the function to build the validation model for form elements.
-
EPiServer.Forms.Core.Internal
. Describes those classes moved to the 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 on the client side. - The class
FormBusinessService
. Calculates the next step to be displayed. You extract the functionGetAllDependee
from the classFormsExtension
and add it to this class. - The class
ProgressiveSubmitInfoService
. Stores and retrieves the progressive submitted 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.
- The class
-
EPiServer.Forms.Core.Data
. Describes those classes moved to the UI project under this namespace. -
IFormDataRepository
.Two data storage-related features let administrators set up read-only mode and let 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 code also lets clients pass a submission storage for data operations, facilitating the need for form customization from clients.
-
EPiServer.Forms.Helpers.Internal
. Describes those classes moved to the 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
andGetFormExternalResources
are moved toFormContainerBlockController
.GetFieldsExcludedInSubmissionSummary
,RenderTextWithEmptyPlaceHolders
, andRenderTextWithPlaceHolders
are moved to the classFormParagraphTextService
.HasAccessRightToReadFormData
is moved toAddon.Helper
.GetSubmittableStatus
is changed toGetFormSubmittableStatus
and moved toSubmitButtonElementBlock
.
CaptchaGenerator
. Generates images containing random text strings.ModuleHelper
. Provides the functions for mapping paths and the host environment.EPiServer.Forms.Configuration
. Describes those classes moved to the UI project under this namespace.Settings
class. Contains the global settings ofEpiForms
. The propertyVisitorGroupProperties
is removed from the classSettings
. That property of the classBuiltinVisitorDataSourceConfig
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 toEPiServer.Forms.EditView
.FormsRazorViewEngine
. Its namespace is changed toEPiServer.Forms.EditView
.ConstantsFormsUI
. Contains constant values of the UI project.PropertyGenericList
class. Displays the user interfaces for configuring complex form elements such asImageChoice
,Validator
, and so on. in EditView.ICustomViewLocation
interface andCustomViewLocationBase
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 the 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 the configuration.FeedService
class. Accesses the Feeds and pre-configures the feed of items. Its new namespace isEPiServer.Forms.EditView.Internal
.OAuthXmlFeed
class. Takes items from an XML string, enables the authentication fulfilling by OAuth, and fetches data from a remote URL.XmlFeed
class. Takes items from aXmlString
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 the UI project under this namespace. Those only are used in EditMode, so 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 from external data sources. Its new namespace isEPiServer.Forms.EditView.Controllers
.FormsElementStore
class. Retrieves the form element information and is moved to the UI project.VisitorDataSourceStore
class. Retrieves visitor data.
-
EPiServer.Forms.EditView.DataTransfer
. Describes those classes moved to the 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 the UI project under this namespace.IOptionItem
interface andOptionItem
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 the 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 the UI project under this namespace or the one nested within it. Although the following classes belong to the UI project, the namespaceEPiServer.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 a JSON array anymore.
Example:
Version 2 format: [{"Key":"keyname","Value":"objectvalue"},{"Key2"...] Version 3 format: {"keyname":"objectvalue","keyname2"...}
-
-
Forms
Main components
This should be the default working web solution. With this package installed, an Editor can create a form immediately without requiring software development. The forms package depends on Core and UI using NuGet dependency. For this package, you 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 visitors)
- 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 ofweb.config
and setfreegeo
asdefaultProvider
.
<geolocation defaultProvider="freegeo">
<providers>
<add name="freegeo" type="EPiServer.Forms.Internal.GeoData.FreeGeolocationProvider, EPiServer.Forms" geoApiUrl="http://freegeoip.net/json/{0}" />
</providers>
</geolocation>
- New exposed API lets you choose different geo-location data providers for his site.
- Create a geo-location provider class that inherits
EPiServer.Personalization.GeolocationProviderBase
andEPiServer.Forms.Implementation.Providers.GeolocationProviders.ICustomGeolocationProvider
. - Create a
GeoDataProcessService
that inheritsEPiServer.Forms.Internal.GeoDataProcessService.IGeoDataProcessService
. - Configure the provider in
web.config
by adding the following line to geo-location section andset defaultProvider=”ProviderName”
and then, add the following line:
<add name="[ProviderName]" type="[fully_qualified_class_name, AssemblyName]"/>
- Added a
FormParagraphTextService
class that replaces a placeholder withFormElement
's value. - Added a
GetFormSubmittableStatus
method to theSubmitButtonElementBlock
class. This method checks whether its form container can be submitted for a given form element. PlaceHolderManager
is marked as Obsolete.SubmissionSummaryElementBlockBase
is marked as Obsolete. (IExcludeInSubmission
should be enough.)- The namespace of
IViewModeExternalResources
is changed toEPiServer.Forms.Implementation
. - The namespace of
FormStep
andFormContainerBlock
is still kept asEPiServer.Forms.Implementation.Elements.
Updated 9 months ago