AI OnAI Off
Paul West

Paul West

Views: 24530
Number of votes: 3
Average rating:

Introducing Page Providers

Oct 07, 2008

Are you looking for a way of integrating external information/data with an EPiServer Web site? With the release of EPiServer CMS 5 R2 it is possible to integrate EPiServer with most data sources. This is achieved by implementing your own custom page provider.

›› Introduction to page providers
›› Page Providers in short
›› Download XmlPageProvider and xml file
›› Adding the XMLPageProvider to a solution
›› Creating custom page providers
›› XMLPageProvider source code
›› Important to consider
›› Further Information

Introduction to page providers

A page provider is a module that when registered with EPiServer CMS 5 R2 can serve an EPiServer CMS 5 R2 Web site with external data (as PageData objects). An EPiServer CMS 5 R2 site can have several different page provider instances registered, each of them having their own set of configuration data such as capabilities settings. The page provider technology is a new way of integrating external information into an EPiServer CMS 5 R2 Web site. The sample page provider XMLPageProvider is shipped with EPiServer CMS 5 R2.

 In this article we shall introduce the concept of page providers and demonstrate XMLPageProvider - a sample page provider aimed at providing insight into how the technology works and hopefully giving you as a developer inspiration to create your own custom page providers. All the data/information appears as part of the EPiServer Web site, though in fact the data/information resides at the data source. The information handled by the page provider can be displayed as EPiServer pages only.  There is no default page provider information in the web.config - this information needs to be added manually.

Page Providers in short

You do not need a special license to use custom page providers (e.g. XmlPageProvider) when running the site in a WebDev server. Though  in order to host the site in IIS and having your own custom page provider, you are required to have an EPiServer Enterprise license. A non commercial developer license is available immediately - you can request one here at EPiServer licenses, remember to insert the text "Enterpise" in the comment section. 

Page Providers in short:

  • Data resides in original store - not in the local EPiServer Web Site database
  • Pages only - the information from a page provider appears as EPiServer CMS 5 pages
  • There is the LocalPageProvider...
  • and the RemotePageProvider (Another EPiServer Web site)
  • Custom page providers require coding and configuration
  • Sample page provider available - XMLPageProvider
  • Requires Enterprise License (not examples such as XMLPageProvider)
  • Versioning, Multi-language, Access rights, Editing and more

Download XmlPageProvider and xml file

Download the XMLPageProvider (assembly), source code and xml file here on EPiServerWorld.

Adding the XMLPageProvider to a solution

Here we shall explain how you can add the XMLPageProvider to a Web site, the public templates package has been used as the solution in this demonstration. You only need to perform a few simple steps in order get the XMLPageProvider working in a Web solution:

Step 1 - Create a page - create a page provider entry point

Insert a page provider node in the site's page tree - we have named the page MyXMLPageProvider. This is the entry point for the XMLPageProvider - observe that it is and must be empty to begin with. Note that the Page ID is given as the value for the entryPoint attribute in the Web.config. The entryPoint attribute specifies which existing page in EPiServer is the root for the pages served by the page provider instance.


Step 2 - Add the XmlPageProvider assembly 

Add the assembly XmlPageProvider.dll to the projects references.

Step 3 - Add  XML file

Now add the downloaded xml file externalpages.xml included in the zip file to the Web site solution folder, this is used as the data storage for this demonstration.  The path and file name for the data file is stored in the attribute filePath in the path provider configuration in the web config file. In this demonstration the xml-file exists in the solution folder.

Step 4 - Add the configuration in web.config

In order to hook up Xml file with the XMLPageProvider in the the solution some configuration needs to be added to web.config. There is no default page provider information in the web.config, this section needs to be added manually. The following is the XMLPageProvider information in the web.config:          

<episerver xmlns="http://EPiServer.Configuration.EPiServerSection">

...

<pageProvider>

<providers>

<add name="XmlPageProvider" type="CodeSamples.XmlPageProvider, XmlPageProvider"   entryPoint="26" capabilities="Create,Edit,Delete,Move,Copy" filePath="~\externalpages.xml"/>

</providers> 

</pageProvider>

...   

</episerver>

 

View the results - XMLPageProvider is now integrated with EPiServer

Now you should be able to create, edit, move and delete pages - under the page provider root page, the information will be updated at its source - in this case the xml file.

As the information is moved into a new page provider and is deleted from the old page provider permanently be careful when moving pages from the page provider!  In order to be able to move pages from the page provider special permissions must be switched on in: Admin Mode->Security->Permissions for Functions->Allow users to move data/pages between page providers.

A warning dialog will still be displayed as an extra precaution when moving pages from the page provider.

Creating custom page providers

Each page provider that is registered with EPiServer must inherit from the PageProviderBase class that resides in the EPiServer.dll assembly. When creating custom page providers there are four abstract methods that are required to be implemented:

  • GetLocalPage
    Is used to pull out one specific page from the data store and return it - a PageData object or an instance of an object that is derived from the PageData class. There are some helper methods in PageProviderBase to initialize and populate PageData objects.
  • GetChildrenReferences
    Only passing back the page references for all the children to one specific node (the rest EPiServer takes care of - caching, sorting etc).
  • Uri ResolveLocalPage(PageReference, out Guid): From a pageReference to a GUID. If the passed in identifier corresponds with an identifier for a page served by the page provider instance then this method should return the internal (“classic” link to the page and the Guid based identifier for the page. This maps to PageLink, PageGUID and LinkUrl properties for a PageData instance.
  • Uri ResolveLocalPage(Guid, out PageReference
    From a GUID to a pageReference. If the passed in identifier corresponds with an identifier for a page served by the page provider then the implementation should return the internal ("classic") link to the page and set PageReference identifier. The URI can be constructed by helper method ConstructPageUri(Int32, PageReference). This typically maps to PageLink, PageGuid and LinkUrl properties for a PageData instance.

XMLPageProvider source code

The XMLPageProvider source code can be downloaded and used as inspiration when developing your own custom page providers, it is included in the zip file along with the XMLPageProvider assembly. The XMLPageProvider example implements many more methods than the mandatory four abstract methods. The XMLPageProvider handles pages stored in a Xml file. The following methods are implemented in order to handle the xml data and to create, edit, move and delete pages:

  • Copy
    Copy a page to another container internally within pages served by this page provider instance.
    Copy between page provider instance is to be seen as Create of new page on destination provider instance.
  • Delete
    Delete a page from the storage.
  • DeleteChildren
    Delete children recursively for a page
  • DeleteLanguageBranch
    Delete a language branch for a page.
  • GetChildrenReferences
    Returns references to all children of the specific page.
  • Search
    Search for pages that fulfill specific criteria.
  • GetLocalPage
    Reads data from the backing XML file and creates a PageData object from the data.
  • Save
    Save page to xml file with specified action.
  • Move
    Move a page to another container served by the same page provider instance.
    Move between page provider instances is to be seen as Save of new page on destination provider followed by a Delete on source provider.
  • ResolveLocalPage
    Resolves the Guid based identifier for a page and the URI (in "classic" format) for a page given the PageReference.
  • ResolveLocalPage
    Resolves the PageReference based identifier for a page and the URI (in "classic" format) for a page given the guid based identifier.
  • FindPagesWithCriteria
    Search for pages that fulfill specific criteria.
  • ListVersions
    Lists all versions
  • SetCacheSettings
    We add additional cache dependency to our backing xml file.
  • ListPublishedVersions
    Lists all published versions
  • ListPublishedVersions
  • LoadPublishedVersion
  • DeleteVersion
    Deletes specified version

Important to consider

Here are some important points to consider when implementing a custom page provider:

  • When creating custom page providers always use complete PageReference objects as parameters. DO NOT simply pass the page ID.
  • Page Providers use the RemoteSite property of PageReference
  • When serializing use PageReference.ToString()
  • When deserializing use PageReference.Parse() or PageReference.TryParse()

Further Information

For further information see:

 

 

Comments

Please login to comment.