Links in Umbraco are Broken, but Alternatives Exist

Published in

Code 101

7 min readNov 29, 2016

TLDR: Archetype fixes most of the things wrong with Umbraco’s built-in property editors geared toward creating links to content, media, and URL’s. To understand what Archetype fixes, read on…

Umbraco’s Built-in Linking Property Editors

You have a few options for creating links in Umbraco 7, including:

Textbox
Media Picker
Content Picker
Multinode Treepicker
Related Links

Here is a content node with an example of each of these property editors:

The built-in property editors for linking to content, media, and URL’s in Umbraco.

Many of those appear to be OK options, until you run across their limitations. Let’s discuss a few of those limitations.

Textbox

This is a flexible option for creating links, as you can link to content, media, external URL’s, and you can attach query strings and document fragments to each of them.

The main downside is that links created with the textbox property editor are susceptible to breaking over time for internal links. That is, any content or media that modified (e.g., renamed or moved) will then have a different URL. This means that any links to those pages and media items will no longer work.

This is somewhat ameliorated by the fact that Umbraco now has automatic redirect creation when content changes. However, it would be better if you linked directly to the content you are intending to link to rather than to a former location that just happens to have a redirect to the new location. This is better for SEO, and it opens up the old URL’s for use by new content.

Another downside is that it can be tiresome for a content editor to have to find the URL of the content nodes and media items so they can copy/paste them into the textbox. On top of that, it would be very easy for content editors to copy the entire URL (including the domain), which could cause links to navigate across environments (e.g., if you restore your production database to your staging environment, you might still have links that point directly to production).

When it comes to using textboxes for links, the only good situation to use them would be for links to external domains.

Media Picker

The obvious limitation of the media picker is that it can only link to media (i.e., it’s not flexible enough to link to content or external links). On top of that, you can’t attach a suffix to the linked media item (e.g., if you want to set a query string of “?width=100” to constrain the width of the image).

Still, media pickers can be a workable solution if all you need to do is link to a media item (e.g., an image or PDF).

Content Picker

Much like the media picker, the content picker’s downfall is its restrictive nature. That is, it can only link to content, and it cannot link to media items or external websites. And again, you can’t specify a suffix to append to the URL of the linked content.

There are situations where the content picker shines, however. For example, if you have a node that contains settings, you might choose that settings node from your homepage. In this case, the content picker makes perfect sense, as it doesn’t allow you to choose a link that isn’t usable in this context.

Multinode Treepicker

The multinode treepicker is interesting in that it is essentially a combination of the media picker and the content picker. That makes it a little more flexible, though sadly it can’t be configured to allow both content and media to be picked (i.e., you must choose one or the other, but not both).

It also has the benefit that you can pick multiple items (i.e., two, three, or more content nodes). It even has some options to configure the start node in sophisticated ways, and to only allow content nodes of particular types to be picked. This can be useful when you really want to lock down what content editors can choose (refer to the settings node example mentioned previously).

Like the other pickers, however, the multinode treepicker is unable to attach a suffix to a URL for a content node or media item. If you wanted to link to the “#employees” section of the about page, you would not be able to do so in the multinode treepicker.

Bonus: Custom Property Editors

One nice thing about the above mentioned property editors is that they are part of the core of Umbraco, and Umbraco is open source. This means that you can create your own property editors by tweaking the existing ones. In fact, we at Rhythm have created a few sites with what we called “composite links”, which was essentially a copied version of the related links property editor with the added ability to attach suffixes.

While this opens up a lot of options, custom property editors still take a good amount of developer time to build, and developers are not a cheap resource. The ideal option would not require very much developer time. On top of that, customized versions of the built-in property editors don’t benefit from upgrades to the Umbraco core, as the code diverges and doesn’t change with the main code base. This means that custom property editors are an expensive short term solution; we can do better.

Enter Archetype

Archetype can be hard to describe, but it’s basically a super property editor that allows you to combine other property editors in new ways. You can even create the bulk of your content entirely in Archetype, though that is beyond the scope of this article. For this article, we’ll just elaborate on how Archetype makes working working with links much nicer.

I won’t bore you with the details of everything Archetype can do; I’ll just start off by showing you what an empty Archetype looks like:

An empty Archetype, before you’ve added any content.

If you click the “Add an item” link, you are presented with a dialog (supposing you’ve configured your Archetype in the same way I have):

Archetype allows you to configure these “fieldsets” yourself.

Note that you are presented with each of your link options (i.e., content, media, and external). Archetype doesn’t force you to choose just one; you can mix different types of links together. Here’s what the content link might look like:

Note that it has everything we might want (a label, a separate title for SEO, a picked content node, a suffix for the query string and document fragment, and a checkbox to optionally open in a new window). You can also mix different types of links:

Three different types of links in Archetype.

Pretty amazing. What’s even better is that configuring this Archetype to allow for these three types of links took about 5 minutes. You don’t even need to spend those 5 minutes doing this yourself. Because Archetype has a “developer options” when editing the Archetype configuration in the data types tree, you can simply paste in the JSON from my Archetype:

All you need to do is paste the above into the “config model” textarea:

You can share your Archetype configurations by copying/pasting this config model.

Happy Coding

That’s really all there is to it. Install Archetype, paste in that bit of JSON, and you’ve got yourself a much improved mechanism to create links in Umbraco.

There are some refinements you can make, such as styling the Archetype properties to remove some of the excess indentation, or adding additional types of links (e.g., overlays). However, those are topics for another day.

For now, you can start reading up on Archetype at these URL’s:

If you have any questions, feel free to contact me or Rhythm Agency, the company I work for. We love working with Umbraco, and we’d love to help you build whatever you need.