EPiServer CMS 4.62
Document creation date:
EPiFields is an add-in to EPiServer CMS, enabling the editor to enter variable data into Web pages. To get the most out of this technical note, you should preferably be an experienced EPiServer CMS developer.
System RequirementsInstallation Instructions
EPiFields Samples Details
EPiFields requires an installation of EPiServer CMS 4.40 or later.
The EPiFields installation is made up of two parts:
Follow the instructions below to install the EPiFields program.
Change the file name by selecting each page type on the Page Type tab in Admin mode and then clicking Settings. The file name can be found on the Information tab.
The instructions in the previous chapter will install basic EPiFields functions. Follow the instructions below to add the sample adapter and sample pages.Save EPiServer.Fields.BaseSample.zip to your computer.
After installing EPiFields, you can only use EPiFields in the Editor in EPiFields - Ordinary Page page types. To add EPiFields support to other page types, e.g. ordinary Web pages, follow the instructions below.
EPiFields is a mechanism that embeds specific HTML tags into the HTML content and resolves them at runtime to inline-generated HTML, performed by customisable PageAdapters. If you are familiar with the concept of field codes in Microsoft Word, you should find it easy to understand the idea behind EPiFields.
EPiFields is based on the following components:
The following chapter explains how the EPiFields samples work together.
This chapter describes the files included in the sample PhrasePageAdapter: PhrasePageAdapter.ascx and the code-behind file PhrasePageAdapter.ascx.cs.
The PhrasePageAdapter is the PageAdapter used to embed standard text phrases entered using the new page type EPiField - Phrase, which simply consists of one property: "TextPhrase". PhrasePageAdapter.ascx is extremely simple. It simply writes out the Data property of the PhrasePageAdapter class, and is not handled further in this document.
In the code-behind file, PhrasePageAdapter.ascx.cs, there are some things to notice. First, the class is given the PageAdapter attribute, which enables EPiServer plug-in loader to locate and load the class. The attribute specifies four settings:
sPageTypeGUID is used to bind this PageAdapter to a specific page type. You may instead override the method ActivateForPage() to handle the activation yourself. This is described in more detail later in the document.
Description is simply a descriptive text.
Url points out the relative path to the PageAdapter .ascx file.
Additionally, a LanguagePath may also be specified if your PageAdpater utilises localised text strings. Refer to the EPiServer CMS SDK and PlugInAttribute for more detailed information about this.
The PhrasePageAdapter derives from the base class PageAdapter (which in turn derives from System.Web.UI.UserControl). The PageAdapter base class provides basic functionality, such as state management to/from a Base64-encoded string, as well as keeping a PageReference to the target page.
When the PhrasePageAdapter is loaded, it calls DataBind() on itself. The ASP.NET framework would then identify the <%# Data %> reference and callback into the Data property. The Data property loads the PageData and retrieves the “TextPhrase” property which is then returned, and is lastly rendered as the output for the adapter.
If your adapter needs to maintain state, it may do so by overriding the methods LoadState() and SaveState(). By default, these methods do nothing.
Note LoadState()/SaveState() does not replace LoadViewState()SaveViewState(), which may also be used to keep the adapters ViewState. LoadState() is called by the EPiServer.Fields framework to initialise the adapter to a preset state.
Postbacks work by default as specific care is taken when the adapters are called to render themselves during the page-rendering process.
Most adapters will need some kind of settings form to let the user specify how the adapter will render itself. Consider, for example, the CurrentDateTime adapter, for which the user can specify the formatting by selecting from a simple drop-down list.
These tasks are handled by PageAdapterEdit controls, whose sole purpose is to provide a form with controls to be shown in the Insert EPiFields dialog.
A PageAdapterEdit is also a simple Web control deriving from the base class PageAdapterEdit. It too specifies an attribute, PageAdapterEditAttribute, which binds the PageAdapterEdit to its PageAdapter target. See the figure below.
PageAdapterRef = typeof(CurrentDateTime),
Url = "~/EPiServer.Fields/Samples/CurrentDateTimeEdit.ascx",
LanguagePath = "/episerver.fields/samples/currentdatetime"
The above sample shows how the CurrentDateTimeEdit PageAdapterEdit is bound to the CurrentDateTime PageAdapter using the PageAdapterRef directive.
When deriving from PageAdapterEdit controls you must override the base class abstract method DataExchange. The DataExchange method is used to perform a two-way databind of the control. A typical implementation of DataExchange is found below, and comes from the CurrentDateTimeEdit sample.
public override void DataExchange( ref PageAdapter adapter,
DataExchangeDirection direction )
CurrentDateTime cdt = adapter as CurrentDateTime;
switch( direction )
string fmt = cdt.FormatString;
FormatList.Items.FindByValue(fmt).Selected = true;
cdt.FormatString = FormatList.SelectedItem.Value;