Forms 3 - Breaking changes

📘

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:

        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 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.

<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 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:

<add name="[ProviderName]" type="[fully_qualified_class_name, AssemblyName]"/>

• 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.