Lee Crowe
Jan 31, 2011
(5 votes)

EPiServer FilteredPageReference v1.0 Released

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

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

The following settings allow quick editing for a selected page, this functionality was stolen from Joel's PropertyQuickEditPageReference property Winking smile
  •  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 Smile


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.


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


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>

Have feedback?

Please feel free to email or twitter me with any feedback @croweman

Jan 31, 2011


Joel Abrahamsson
Joel Abrahamsson Jan 31, 2011 11:54 PM

Looks really, really interesting. Great work!

Alex Valner
Alex Valner Feb 12, 2011 10:41 AM

Great work! I'm really in need for this custom properties.

Feb 14, 2011 10:52 AM

Hi Alex

Have you checked out my second post about programattically setting a start page http://world.episerver.com/Blogs/Lee-Crowe/Dates/2011/2/FilteredPageReference-v11-Released/


Please login to comment.
Latest blogs
Optimizely For you Intranet

Having been at Optimizely and in the CMS industry for nearly 16 years I have seen clients’ intranet requirements go from a simple site just to hous...

Robert Folan | Sep 22, 2023

Vulnerability in EPiServer.GoogleAnalytics v3 and v4

Introduction A potential security vulnerability was detected for Optimizely Google Analytics addon (including EPiServer.GoogleAnalytics and...

Bien Nguyen | Sep 20, 2023

Overriding Optimizely’s Content Recommendations Block to Implement Custom Recommendations

Introduction The Content Recommendations add-on for Optimizely CMS dynamically recommends content from your site tailored to the interests of each...

abritt | Sep 13, 2023 | Syndicated blog

Developer contest! Install the AI Assistant and Win Bose QC45 Headphones!

We are thrilled to announce a developer contest where you have the chance to win a pair of Bose Headphones. The goal is to be the first developer t...

Luc Gosso (MVP) | Sep 7, 2023 | Syndicated blog

Send Optimizely notifications with SendGrid API, not SMTP

If your Optimizely site already sends transaction emails through an email platform API, why not do the same with Optimizely notification emails?

Stefan Holm Olsen | Sep 6, 2023 | Syndicated blog

Optimizely Configured Commerce Custom POST API

Introduction When creating custom API controllers for an Optimizely B2B project it’s possible you’ll want to create POST calls. Following the...

Dylan Barter | Sep 6, 2023