EPiServer FilteredPageReference v1.0 Released

What is this I hear you all cry.  Well I will tell you

For a few of the projects I have been working on I have been using Joel Abrahamsson's TypedPageReference property control to enforce a referential integrity (for want of a term) for picking pages.

The property is very useful but I wasn't that keen on the idea of creating a new class every time I wanted to enforce a constraint on the types of pages that could be picked.  I also wasn’t keen on the fact that the validation only occurred when a page is saved.

After discussing this with my colleague David Knipe I decided to build an alternative to this.

If you read Joel's blog post he discusses the potential maintenance problems of developing an alternative page browsing page.  I fully agree with the maintenance problems this could introduce but I decided that the potential benefits could outweigh the possible maintenance issues.

Introducing FilteredPageReference

Once you download the 'FilteredPageReference.dll' and place it in your bin you will see that the following two new properties are made available in admin mode:

•  FilteredPageReferenceProperty - This property inherits PropertyPageReference
•  FilteredLinkCollectionProperty - This property inherits PropertyLinkCollection

FilteredPageReference Property Settings

For those of you who are not aware, in EPiServer CMS 6 you can associate custom property settings classes with your custom properties. 

This allows the developer to customize how they want the control to work for different instances of the property.

Each of the properties above have a custom settings class associated with them to allow property configuration.

The available properties are shown and described below:

Tree Starting Point Settings

•  Start Page Tree From - This property provides an InputPageReference control which allows you to pick a page within the page tree to start listing pages from.
•  Current Page - When checked the tree listing will start from the current page.  If the page has not yet been saved then a message will be shown on the custom page browser page to inform the user that the page needs to be saved first.
•  Current Site Start Page - When checked the current sites start page will be used as the starting point for tree listing

Page Picking Restriction Settings

•  Validation Error Message - This is currently only relative to the FilteredPageReferenceProperty.  A default message will be shown if validation fails but this can be overridden by setting the value for this property.  Please be aware that validation does not occur when saving the FilteredLinkCollection property.
•  Restrict To EPiServer Pages - This is only relevant to the FilteredLinkCollection property and when checked the custom HyperLinkProperties dialog will not show the email or document tabs and will not allow a user to pick a non EPiServer Page url.
•  PageTypeBuilder Types and Interfaces - The FilteredPageReference assembly is not dependent on PageTypeBuilder but if the web application is using PageTypeBuilder then all types that inherit TypedPageData and use interfaces of those types will be displayed in a CheckBoxList control.
•  Page Types - This lists all available page types to restrict page picking

Quick Edit Settings

•  Allow Quick Edit - If checked then a quick edit link will appear once a page is selected.
•  Popup Height - The Quick Edit popup window height.
•  Popup Window Width - The Quick Edit popup window width.

Editor Usage

The image below shows an example of what would appear within the custom PageBrowser dialog when the FilteredPageReference property has been configured to start from the news page and only allow News Item page types.

You will see that the picking tree starts from the news page and that one of the pages is shown in italics and is unselectable.

When using the FilteredLinkCollection property and checking the setting to restrict picking to EPiServer pages only you will see a custom HyperLinkProperties page like the following screen dump demonstrates.

I am not going to show/demonstrate all of the alternatives but you should get the general gist of what you can do with the properties from reading the property descriptions above

Problems encountered developing the functionality

There was no easy way to change the behaviour of the various existing pages and user controls used for picking pages.

The only way I could achieve this was to reflect out the code of the existing implementations and modify where necessary to add the required functionality. 

The custom dialogs and user controls are embedded resources of the FilteredPageReference.dll assembly and are registered programmatically using custom VPP providers.

Important

As custom pages and user controls are used to provide the custom picking functionality the existing PropertyPageReference and PropertyLinkCollection functionality will not be affected.

Installation and Setup

The FilteredPageReference assembly will only work with EPiServer CMS 6 and onwards.

To install just simply place the assembly into your web applications bin folder.  The assembly can be downloaded from

http://episerverfpr.codeplex.com/.

To globalize the various labels and text used by the dialogs and property controls add the following settings to the relevant lang.xml file. 

   1:  <?xml version="1.0" encoding="utf-8" standalone="yes"?>

   2:  <languages>

   3:    <language name="English" id="en">

   4:      <filteredPageReference>

   5:        <pageMustBeSaved>The page must be saved before you can pick a page.</pageMustBeSaved>

   6:        <selectedPageIsNotValidMessage>The selected page for property '{0}' is not of a valid page type.</selectedPageIsNotValidMessage>

   7:        <selectedPageTypesWithValidPageTypesMessage>The selected page for property '{0}' is not of a valid page type.  Valid page types for this property are: {1}</selectedPageTypesWithValidPageTypesMessage>

   8:        <treeStartingPoint>Tree Starting Point</treeStartingPoint>

   9:        <startPageTreeFrom>Start Page Tree From</startPageTreeFrom>

  10:        <currentPage>Current Page</currentPage>

  11:        <currentSiteStartPage>Current Site Start Page</currentSiteStartPage>

  12:        <pagePickingRestrictions>Page Picking Restrictions</pagePickingRestrictions>

  13:        <validationErrorMessage>Validation Error Message</validationErrorMessage>

  14:        <restrictToEPiServerPages>Restrict To EPiServer Pages&lt;br /&gt;(Filtered Link Collection)</restrictToEPiServerPages>

  15:        <pageTypeBuilderTypesAndInterfaces>PageTypeBuilder Types and Interfaces</pageTypeBuilderTypesAndInterfaces>

  16:        <pageTypes>Page Types</pageTypes>

  17:        <quickEdit>Quick Edit (Filtered Page Reference)</quickEdit>

  18:        <allowQuickEdit>Allow Quick Edit</allowQuickEdit>

  19:        <popupHeight>Popup Height</popupHeight>

  20:        <popupWidth>Popup Width</popupWidth>

  21:        <quickEditLinkText>Quick edit</quickEditLinkText>

  22:      </filteredPageReference>

  23:    </language>

  24:  </languages>