Links in Umbraco are Broken, but Alternatives Exist
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:
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.
Related Links
The related links property editor is a bit like a combination of the textbox and the content picker. That is, it allows you to either specify a URL manually by typing it into a text field, or to pick a content node. On top of that you can specify a caption and you can indicate whether or not the link opens in a new window. And similar to the multinode treepicker, multiple links can be entered. That sounds pretty useful, but there are still drawbacks.
For one, like most every other property editor in Umbraco, no suffixes can be specified for links to content nodes. Also, you can’t link to media, except for with a manual URL. Additionally, there is no extra text field for a title (e.g., if you want your links to have title attributes that are more informative than the text in the links, which can improve accessibility). And while it’s an uncommon scenario, there is no way to configure the related links property editor to default the new window checkbox to checked (i.e., in case you have particular links that tend to open in new windows).
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:
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):
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:
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:
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:
- https://our.umbraco.org/projects/backoffice-extensions/archetype/
- https://github.com/kgiszewski/ArchetypeManual
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.