EPiFields Developer Information

Transcription

1 EPiFields Developer Information Product version: Document version: 1.0 Document creation date: Purpose EPiFields is an EPiServer add-in, 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 developer. The contents of this document are protected by copyright. Contents of the document may be freely copied and distributed, either digitally or in printed format, to all EPiServer users. EPiServer is a registered trademark of ElektroPost Stockholm AB. Other product and company names mentioned in this document may be the trademarks for their respective owners.

2 2 EPiFields Developer Information Table of Contents SYSTEM REQUIREMENTS 2 INSTALLATION INSTRUCTIONS 2 WHAT IS EPIFIELDS? 3 EPIFIELDS SAMPLES DETAILS 3 PHRASEPAGEADAPTER OVERVIEW 4 PAGEADAPTEREDIT 5 System Requirements EPiFields requires an installation of EPiServer See the white paper, "Getting Started with EPiServer 4" for information on EPiServer's system requirements. 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. Open the downloaded.zip file and copy all the files under the /WebRoot folder to the root of your EPiServer Web. Installing the EPiFields Sample Pack Follow the instructions below to add the sample adapter and sample pages. 1. Save EPiServer.Fields.BaseSample.zip to your computer. 2. Open the downloaded.zip file and copy all the files under the /WebRoot folder to the root of your EPiServer Web site. 3. Copy the file EPiFieldsBaseLibrary.epi4 from the /ImportFiles folder to your computer. Go to Admin mode and select Import data under the Tools section. Select the export file EPiFieldsBaseLibrary.epi4. Select your Web root in Select page destination and click Begin Import. 4. In Admin mode, select the new function EPiServer Fields Settings under the Tools section. Set the EPiField Base Library as the root page and save the settings.

3 What is EPiFields? 3 5. Go to Edit mode and move the /EPiFields Sample Pages folder, currently placed under /root/epifield Base Library, to another location on your Web site. 6. You are now ready to try EPiFields. 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-anddrop 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.

4 4 EPiFields Developer Information 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 och 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 = "{A13F BFA BD4C5F7}" Description = "Display standard text phrase" Url = "~/EPiServer.Fields/BaseSamples/PhrasePageAdapter.ascx" LanguagePath = "/episerver.fields/basesamples/phrasepage"

5 PageAdapterEdit 5 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 EPiServer4 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. [ PageAdapterEdit( PageAdapterRef = typeof(currentdatetime), Url = "~/EPiServer.Fields/Samples/CurrentDateTimeEdit.ascx", LanguagePath = "/episerver.fields/samples/currentdatetime" ) ]

6 6 EPiFields Developer Information The above sample shows how the CurrentDateTimeEdit PageAdapterEdit is bound to the CurrentDateTime PageAdapter using the PageAdapterRef directive. PageAdapterEdit Two-Way Databinding 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 ) { case DataExchangeDirection.GET: string fmt = cdt.formatstring; FormatList.Items.FindByValue(fmt).Selected = true; break; case DataExchangeDirection.SET: } } cdt.formatstring = FormatList.SelectedItem.Value; break;