Forms 3 - Breaking changes

📘

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 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 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 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 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 function GetAllDependee from the class FormsExtension 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.

• 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 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 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 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 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 is EPiServer.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 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 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 is EPiServer.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 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 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 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 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 of web.config and set freegeo as defaultProvider.

<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 and EPiServer.Forms.Implementation.Providers.GeolocationProviders.ICustomGeolocationProvider.
• Create a GeoDataProcessService that inherits EPiServer.Forms.Internal.GeoDataProcessService.IGeoDataProcessService.
• Configure the provider in web.config by adding the following line to geo-location section and set 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 with FormElement's value.
• Added a GetFormSubmittableStatus method to the SubmitButtonElementBlock 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 to EPiServer.Forms.Implementation.
• The namespace of FormStep and FormContainerBlock is still kept as EPiServer.Forms.Implementation.Elements.