Page Providers
|
Product version: |
EPiServer CMS 5 R2 SP1 |
|---|---|
|
Document version: |
1.0 |
|
Document last saved: |
Introduction
This technical note contains functional and technical information about the Page Provider concept. A page provider is a module that when registered with EPiServer CMS can serve the EPiServer CMS site with exteral data as PageData objects. An EPiServer CMS site can have several different page provider instances registered with each of them having their own set of configuration data such as capabilities settings, etc.
Table of Contents
Prerequisities
An Enterprise license is required to use custom page providers, i.e. page providers not included with EPiServer CMS.
Configuration
The registration of a page provider with EPiServer CMS can be done either through configuration in web.config (see below) or programatically through API class EPiServer.PageProviderMap.
Every class registered as a page provider must inherit the base class EPiServer.Core.PageProviderBase, which is based on System.Configuration.Provider.ProviderBase. To register the page provider in web.config an entry should be added to the configuration element pageProvider, see the example below.
<episerver xmlns="http://EPiServer.Configuration.EPiServerSection">
...
<pageProvider>
<providers>
<add name="custom" type="CustomServer.PageStore, Custom" entryPoint="52" capabilities="Create,Edit,Delete,Search"/>
</providers>
</pageProvider>
...
</episerver>
Mandatory attributes are name, type and entryPoint. The entryPoint attribute specifies which existing page in EPiServer CMS will be the root for the pages served by the page provider instance. The given entryPoint must not have any existing children in EPiServer CMS.
iconPath is an optional attribute which makes it possible to display a custom icon in the page tree for each page served by the provider instance. The given path should be a relative path to the folder \Images\ExplorerTree\PageTree\ in the themes folder, e.g. if an image custom.gif is placed in App_Themes\Default\Images\ExplorerTree\PageTree, the value of the iconPath attribute should be custom.gif.
wastebasketName is an optional attribute for what the Recyle Bin for the page provider instance is called. If not given, the Recycle Bin will have the same name as the provider is registered with.
It is possible to specify which capabilities the provider instance supports. The available capabilities are:
-
Create: States if the provider supports creation of new pages. This capability implies that the class should implement method Save.
-
Edit: States if the provider supports edit of existing pages. This capability implies that the class should implement method Save.
-
Delete: States if the provider supports deletion of existing pages. This capability implies that the class should implement methods Delete and DeleteChildren, it also needs to implement MoveToWastebasket (or Move with WastebasketReference as destinaltionLink) .
-
Copy: States if the provider supports copy of pages internally within the pages served by the page provider. To support copy between providers the capability to support is Create. The Copy capability implies that the class should implement method Copy.
-
Move: States if the provider supports move of pages internally within the pages served by the page provider. To support move between providers the capability to support is Create and Delete. The Move capability implies that the class should implement method Move.
-
MultiLanguage: States if the provider supports that pages have multiple language versions. This capability implies that the class should implement method DeleteLanguageBranch and that the implementation of Save handles multiple languages. It should also take passed in ILangaueSelector in consideration when serving pages.
-
Search: States if the provider supports search within the properties for the pages served by the provider. This capability implies that the class should implement method FindPagesWithCriteria.
-
Security: States if the access checks for pages delivered by the provider should be performed on the pages itself (through calls to ISecurable interface on PageData or inherited class). For providers not supporting Security capability the access check will be performed on page specified as entryPoint for the provider. Practically this can be seen as that the ACL is inherited from the entryPoint page to all pages served by the provider instance.
Several capabilities can be specified by a comma-separated list.
Move between page providers requires that the user has permission for function "Move between page providers".
PageProviderBase
Each class that is registered with EPiServer CMS as a page provider must inherit the class EPiServer.Core.PageProviderBase that resides in assembly EPiServer.dll. The base class contains some abstract methods that must be implemented e.g. GetLocalPage, ResolveLocalPage etc. The base class also contains some virtual methods that can/need to be overriden if some capabilities are to be supported, see the Configuration section.
The base class also offers some helper methods to work with PageData objects. One such method is InitializePageData which initializes a PageData object with metadata properties and properties given by the specified page type it also set some default values on metadata properties. Another method is SetProperties that set values for properties on a PageData object. Yet another helpful method is GetProperties that extracts data from a PageData object to a Dictionary so it can be passed/stored to some other back-end storage.
A sample page provider XmlPageProvider is available on EPiServer World. The sample page provider implements most of the possible capabilities (currently all but versioning and searching).
Search
If a page provider instance is to be searchable, it must be registered with the Search capability and the class registered must implement FindPagesWithCriteria.
Below is a description on how to call FindPagesWithCriteria depending on which page providers is to be included in the search.
Specific Search on a Specific or Many Custom Page Providers
Searching on a specific Custom Page Provider or even many Custom Page providers is done by adding a PropertyCriteria for each Custom Page Provider to PropertyCriteriaCollection.
The name of property should be "EPI:MultipleSearch" and the value should be the name of Custom Page Provider.
Here is example code for that:
PropertyCriteriaCollection crits = new PropertyCriteriaCollection();
PropertyCriteria crit = new PropertyCriteria();
crit.Name = " MultipleSearch";
crit.Value = “CustomKey”;
DataFactory.Instance.FindPagesWithCriteria(customPageRef, crits);
Search on All Custom Page Providers
Searching on all Custom Page providers can be achieved be by defining only one PropertyCriteria. The name of the PropertyCriteria should be "EPI:MultipleSearch" and the value should be "*".
Here is an example code for that:
PropertyCriteriaCollection crits = new PropertyCriteriaCollection();
PropertyCriteria crit = new PropertyCriteria();
crit.Name = " EPI:MultipleSearch";
crit.Value = “*”;
DataFactory.Instance.FindPagesWithCriteria(customPageRef, crits);
Search on Default Page Provider (typically the one serving pages from the EPiServer CMS database)
The Searching will work as before if there is not PropertyCriteria with name “EPI:MultipleSearch”.
NOTE: Full text search is implemented only for the default (Local) Page Provider. This means that pages serverd by custom page providers are not indexed and will not be searchable by using EPiServer SearchDataSource control.
Remote Page Provider
Remote Page Provider is available on the Codeplex open source community Web site. Documentation about the Remote Page Provider can be found on the Codeplex Web site.
A Remote Page Provider is used to integrate the content between two installations of EPiServer CMS. Pages appear as any local page even when they are managed by a separate installation.
