Thursday, 12 February 2009

EPiServer 5 R2 and Link Collection property

With EPiServer 5 R2 new property type was released -- Link Collection. It looks like a EPiServer's version of very popular Mulitipage property. In this post I would like to show you exactly how it can be used and also what are the pros and cons.

After adding a property of this type to a page you will see in edit mode this:


And with a few links added property looks like this:


This is first significant change comparing to old Multipage property (MP) -- list of all links is visible on the page. With old MP it was necessary to click on the button to get a popup with a list of links. That is a good change!

What is missing here for me is a ability to test links. Text which you can see for the first item on the list is not necessary a page name (it might be a clickable text) so it's impossible to figure out from this view what page is referenced.

Funny thing is that title for this link has a following form:

It is very useful isn't it? ;) I think the simplest solution would be to make link text clickable.

After clicking on 'Add Link' or 'Edit' button you will get old popup:


There are no surprises here, it's an old well-know dialog.

Lets check now how to deal with Link collection in a code. It's quite common to use Repeater to display links:

   1:  <asp:Repeater ID="rptRelatedLinks" runat="server">
   2:      <HeaderTemplate><dl></HeaderTemplate>
   3:      <ItemTemplate><dt><asp:HyperLink runat="server" ID="hplMainLink" /></dt></ItemTemplate>
   4:      <FooterTemplate></dl></FooterTemplate>
   5:  </asp:Repeater>

And here is a code to get links from the CurrentPage:

   1:  PropertyLinkCollection links = (PropertyLinkCollection) CurrentPage.Property["RelatedLinks"];
   2:  rptRelatedLinks.DataSource = links;
   3:  rptRelatedLinks.DataBind();

And a method populating the Repeater:

   1:  void rptRelatedLinks_ItemDataBound(object sender, RepeaterItemEventArgs e)
   2:  {
   3:      if (e.Item.ItemType == ListItemType.Item || e.Item.ItemType == ListItemType.AlternatingItem)
   4:      {
   5:          LinkItem linkItem = (LinkItem) e.Item.DataItem;
   6:          HyperLink link = (HyperLink) e.Item.FindControl("hplMainLink");
   7:  
   8:          // mapped link has a form like:
   9:          // <a href="/Templates/Public/Pages/Page.aspx?id=16&epslanguage=en" target="_blank" 
  10:          //       title="this is link title">Information about the meeting</a>
  11:          string mappedLink = linkItem.ToMappedLink();
  12:          
  13:          // permanent link form:
  14:          // <a href="~/link/bb6aa3227f8f467bbe1a42154cb56ba5.aspx" target="_blank" 
  15:          //           title="this is link title">Information about the meeting</a>
  16:          string permanentLink = linkItem.ToPermanentLink();
  17:  
  18:          // because Href property will return permanent link like 
  19:          // ~/link/bb6aa3227f8f467bbe1a42154cb56ba5.aspx
  20:          //
  21:          // it's necessary to use PermanentLinkMapStore.ToMapped(url) to covert it to normal form
  22:          // result is required to determine if conversion was successful
  23:          // it will fail for mails (mailto:test@test.com), documents and external links
  24:          UrlBuilder url = new UrlBuilder(linkItem.Href);
  25:          bool result = PermanentLinkMapStore.ToMapped(url);
  26:  
  27:          link.NavigateUrl = result ? url.ToString() : linkItem.Href;
  28:          link.Text = linkItem.Text;
  29:          link.ToolTip = linkItem.Title;
  30:          link.Target = linkItem.Target;
  31:      }
  32:  }

The basic problem is that Href property returns permanent link, therefore it's necessary to use PermanentLinkMapStore class to convert the links. ToMappedLink() method returns a full "a" tag, which might be convenient in some cases. Take a look on all properties again:

My overall impression is positive, new property Link collection is easy to use but for sure there are things which could be improved like ability to test a link or ability to define page root to look for pages to include. It's a hassle to always start from the very top!

I wonder now if there is still a reason to use old Multipage property, what do you think?

Related posts:

6 comments:

stevec said...

Good posting explaining the new property collection.

In several cases, I have had the need to know if the "clickable text" (link text) was changed by the editor (from the original pagename) when the link was added. If the editor has not changed the text, I can always go fetch the page and use the PageName or optional a Title property in the link list instead.

Another thing, if you add a link collection property to a page, making it language independent, the links to pages will not change to reflect the page names in the current language (I assume, as I have not tested it.)

The Multipage property handles this if you link to pages, and have not provided your own link text.

I guess there are still more differences between these types of link collections, so we can safely say that the Multipage property is not dead yet ;-)

Marek Blotny said...

Hi Steve, thanks for listing other differences, I wasn't aware of them!

I certainly hope that Multipage property will continue to improve and this way it will be a viable alternative.

Anonymous said...

Just helped me solve an error in our solution :) cheers

Anonymous said...

Great article! I have one question: Why is the clickable image property disabled when adding a new link to the collection? Are image links not supported?

rosy said...

Good posting! web application

Anonymous said...

Hi Mark

Do you have any idea how I could translate a permanent link to it's normal form when the linkitem is a document?

ToMappedLink and ToMapped does not seem to work.

Andreas