Sitecore API: Explain how Sitecore renders links and how they can be controlled

In this post, we will learn how Sitecore renders links and what are different options for controlling the URL.

How Sitecore renders links

The default Sitecore link provider automatically generates SEO compatible URLs for each item based on its name and its path relative to the home item of the context site. While generating the URLs, Sitecore link provider takes care of following:

  • If Rendering.SiteResolving setting is true, and the item is not the home item of the context site or one of its descendants, Sitecore constructs the URL relative to the home item of the managed site which is determined as an ancestor of the item. For example, the URL of the /sitecore/content/Site1/Global/Folder1/Item1 item would be http://sc826/en/Site1/Global/Folder1/Item1 (Refer below code snippet)
    var db = Sitecore.Configuration.Factory.GetDatabase("master");
    var item = Sitecore.Context.ContentDatabase.GetItem("/sitecore/content/Site1/Global/Folder1/Item1");
    Sitecore.Links.UrlOptions urlOptions = (Sitecore.Links.UrlOptions)Sitecore.Links.UrlOptions.DefaultOptions.Clone();
    urlOptions.SiteResolving = true;
    urlOptions.AlwaysIncludeServerUrl = true;
    String url = Sitecore.Links.LinkManager.GetItemUrl(item, urlOptions);
    return url;
  • While constructing the URL of an item, Sitecore removes the path to the start item of the managed site associated with the item. For example, with the default configuration, the URL of the /sitecore/context/home/About us/The organization item would be /About-us/The-organization. (Refer below code snipped)
    var db = Sitecore.Configuration.Factory.GetDatabase("master");
    var item = Sitecore.Context.ContentDatabase.GetItem("/sitecore/content/Home/About us/The organization");
    Sitecore.Links.UrlOptions urlOptions = (Sitecore.Links.UrlOptions)Sitecore.Links.UrlOptions.DefaultOptions.Clone();
    urlOptions.SiteResolving = Sitecore.Configuration.Settings.Rendering.SiteResolving;
    String url = Sitecore.Links.LinkManager.GetItemUrl(item, urlOptions);
    return url;
  • Internal links in the raw field values contain the IDs which Sitecore refers to dynamic links. To convert IDs in field values to friendly URLs based on item paths exactly, you need to do any of the following:
    • Use the Sitecore.Web.UI.WebControls.FieldRenderer web control.
    • Invoke the Sitecore.Web.UI.WebControls.FieldRenderer.Render() static method.
    • Call the renderField pipeline.
    • Call the Sitecore.Links.LinkManager.ExpandDynamicLinks() static method

How to control links rendering

The default link provider supports following attributes (URL options) using which we can control the links rendering:

  • addAspxExtension – Determines whether to include the .aspx extension in the URLs of content items
  • alwaysIncludeServerUrl – Determines whether to include the protocol, such as http, and domain, such as www.domain.tld, in URLs
  • encodeNames – Determines whether to encode characters in item names according to the /configuration/sitecore/encodeNameReplacements/replace element in the Web.config file
  • languageEmbedding – Determines whether to include a language code in URLs
  • languageLocation – Determines whether to use the first steps in the URL path or the sc_lang query string parameter to specify the language code
  • shortenUrls – Reserved for future use by Sitecore
  • useDisplayName – Determines whether Sitecore uses the display names of items to construct URLs rather than using the names of those items