EPiFields Developer Information

Purpose

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.

Table of Contents

What is EPiFields?

PageAdapterEdit
    - PageAdapterEdit Two-Way Databinding

System Requirements

EPiFields requires an installation of EPiServer CMS 4.40 or later.

Installation Instructions

The EPiFields installation is made up of two parts:

• EPiFields - core program files. These files must be installed before the EPiFields sample pack can be installed.
• EPiFields Sample Pack- base samples and integration samples.

Installing the EPiFields Program Files

Follow the instructions below to install the EPiFields program.

1. Save EPiServer.Fields.zip to your computer.
2. Extract the downloaded .zip file and copy all the files under the /WebRoot folder to the root of your EPiServer CMS Web site. This will add:
• images to the /util/images/editor folder,
• language files to the /lang folder,
• EPiServerFields folders to the /edit and /admin folders,
• EPiServer.Fields.dll to the /bin folder,
• an EPiServerFields folder to the Web site root.
3. If you have a version of EPiFields previous to 4.51, you must uninstall the old version by following these steps:
1. Remove the following folders from your Web site root. Make sure you remove the folders with a separating dot between "EPiServer" and "Fields", and not the new folders without dots.
• /admin/EPiServer.Fields
• /edit/EPiServer.Fields
2. In Admin mode, change the file name from "/<my site>/EPiServer.Fields..." to "/<my site>/EPiServerFields..." (without the separating dot between "EPiServer" and "Fields") for the following page types:
• Data Provider SQL
• Data Provider HTML
• Data Provider XML
• EPiField - Ordinary Page
• EPiField - Phrase
• Integration View Page

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.

3. Remove the old EPiServer.Fields folder from your Web site root. Make sure you remove the folder with a separating dot between "EPiServer" and "Fields", and not the new folder without the dot.

Installing the EPiFields Sample Pack

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.

1. Save EPiServer.Fields.BaseSample.zip to your computer.
2. Extract the downloaded .zip file and copy all the files under the /WebRoot folder to the root of your EPiServer Web site. This will add:
• two folders to the /EPiServerFields folder,
• language files to the /lang folder,
• EPiServer.Fields.BaseSample.dll and EPiServer.Fields.Integration.dll to the /bin folder.
3. In Admin mode, click Import Data under the Tools section on the Admin tab. Select the import file EPiFieldsBaseLibrary.epi4 located in the /Import Files folder of the extracted .zip file. Import the content of the file to your Web site root.
4. Still in Admin mode, click EPiServer Fields Settings under the Tools section on the Admin tab. Set EPiField Base Library as the root page and save the settings.
5. In Edit mode, move the EPiFields Samples page, currently placed under /Root/EPiField Base Library, to the location of your choice on your Web site.

Adding EPiFields Support to Non-EPiFields Page Types

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.

1. Go to Admin mode and, from the Page types section, select the page type that you want EPiFields to be available in, e.g. Ordinary Web page.
2. To change the LongString property type, click the MainBody property, which will open the Edit property window. Change the Type field so that it has property EPiServer.Fields.LongString. Click Save.

What is EPiFields?

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:

• EPiServer.Fields.LongString
  A self-registering property type capable of resolving EPiFields tags at runtime.
  To enable EPiFields, the page type’s LongString properties must be modified to instead be based on the new property type EPiServer.Fields.LongString.
  This component will be rendered every time the page is called, which may cause slight performance problems.
• An Editor plug-in
  Provides new Editor functionality through a new toolbar button and also enables drag-and-drop from the EPiServer tree directly into the Editor.
• PageAdapters
  PageAdapters are basically simple Web controls developed to generate appropriate HTML code for a given page type. You may think of a PageAdapter much in the same way as a page template in EPiServer, in that it knows about the page type’s properties and knows how to render those into appropriately formatted HTML. A PageAdapter is usually bound to a specific page type based on the page type’s GUID, but you may develop generic PageAdapters suitable for any page type or PageAdapters that don’t refer to EPiServer page types at all, for example, the CurrentDateTime.

EPiFields Samples Details

The following chapter explains how the EPiFields samples work together.

BaseSamples

• CurrentDateTime.ascx – component that displays time and date.
• CurrentDateTimeEdit.ascx – component stating the format in Edit mode.
• CurrentUser.ascx – component that displays information about the user that is currently logged on.
• CurrentUserEdit.ascx – component stating the format in Edit mode.
• MetaPropertyPageAdapter.ascx – component to handle fields for the selected page.
• MetaPropertyPageAdapterEdit.ascx - component stating the format in Edit mode.
• EPiFieldsPage – page type for pages with phrases.
• EPiFieldsPhrase.aspx – template for handling phrases in EPiFields.
• PhrasePageAdapter.ascx – Adapter for phrases.

Integration

• IntegrationPage.aspx –template for the integration pages can have page types ’Data Provider SQL’, ’ Data Provider HTML’ and ’Data Provider XML’, depending on the different data providers from different sources.
                  DataProviderHTML.sc
                  DataProviderSQL.cs
                  DataProviderXML
• IntegrationView.ascx – displays data given by a provider to a view.
• IntegrationView Edit.ascx – component stating the format in Edit mode.
• ViewGraph.ascx – view for displaying information in a graph
• ViewList.ascx – view for displaying information as a list
• ViewTable.ascx – view for displaying information as a table
• ViewPage.ascx – view for displaying the first post as a page

PhrasePageAdapter Overview

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 = "{A13F2577-0499-4194-BFA0-75048BD4C5F7}"
• Description = "Display standard text phrase"
• Url = "~/EPiServer.Fields/BaseSamples/PhrasePageAdapter.ascx"
• LanguagePath = "/episerver.fields/basesamples/phrasepage"

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.

Maintaining State

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

Postbacks work by default as specific care is taken when the adapters are called to render themselves during the page-rendering process.

PageAdapterEdit

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.

The above sample shows how the CurrentDateTimeEdit PageAdapterEdit is bound to the CurrentDateTime PageAdapter using the PageAdapterRef directive.