Linking

Constellation.Foundation.Linking is a library that allows you to create custom Sitecore Link Manager settings on a site-by-site basis.

Appropriate Scenarios

Scenario 1: Corporate is Different

You have multiple sites installed, including some regional sites, some of which are in multiple languages. The corporate website is a .com and is only available in US English. Marketers don’t want the “/en” or “/en-us” in the URL.

Scenario 2: One Site is Very Old

Of your multiple sites, one is so old it’s built on ASP.NET Webforms and requires the trailing .aspx file extension.

Scenario 3: Each site is in only one language, except Belgium…

Belgian URLs will need the language slug in the URL, but that’s a new idea. None of your other sites specify language in the URL.

Scenario 4: We inherited a site from a 3rd party and they have some really exotic URL generation process.

Perhaps the site is integrated with an e-commerce solution, or uses wildcards for some content… Either way, you want to keep the scope of this link generation logic isolated.

What’s in the Box

  • An initialization routine that automatically replaces the stock LinkManager with SwitchingLinkManager.
  • SwitchingLinkManager, which is a fairly silent partner. It handles the magic of figuring out which LinkProvider to hand you when you make static calls to LinkManager in your code.
  • A pile of comments in the library’s *.config file, which tell you how to create new Providers (re-iterating Sitecore’s documentation). The comments also tell you how to name the Provider that should be used by individual Sites, again, by making changes to the Sitecore config files.

Implementation involves creating named LinkProvider configurations for each variation of LinkProvider that you need in your installation. This can include using the same LinkProvider type but with different options (include language, don’t include extensions, etc…) Finally, for each Site in your installation that needs the non-generic LinkProvider options, you specify the named LinkProvider configuration for that site in it’s <site /> definition element.

SwitchingLinkManager looks at the Context Site when you ask to GetItemUrl(). If the Context Site has a reference to a named LinkProvider configuration, that configuration is used to generate the Friendly Url. Otherwise, the default LinkManager is called, and life proceeds according to Sitecore’s defaults.

Installation

Constellation.Foundation.Linking is managed via NuGet.

In Visual studio, fire up the Package Manager console and install into a Web Application project:

PM:> Install-Package Constellation.Foundation.Linking

After installation, create your own LinkProvider definitions. Here’s an example from a custom configuration file:

<linkManager defaultProvider="sitecore">
  <providers>
    <add name="exampleProvider"
      type="Example.Feature.ExampleProvider, Example.Feature"
      addAspxExtension="false"
      alwaysIncludeServerUrl="false"
      encodeNames="true"
      languageEmbedding="asNeeded"
      languageLocation="filePath"
      lowercaseUrls="true"
      shortenUrls="true"
      useDisplayName="false"/> 
    <add name="exampleProvider-differentconfig"
      type="Example.Feature.ExampleProvider, Example.Feature"
      addAspxExtension="false"
      alwaysIncludeServerUrl="false"
      encodeNames="true"
      languageEmbedding="asNeeded"
      languageLocation="filePath"
      lowercaseUrls="true"
      shortenUrls="true"
      useDisplayName="false"/>
  </providers>
</linkManager>

Finally, you need to patch your site definitions to ensure that each are using the correct LinkProvider configuration. Example follows:

<sites>
  <site name="corporateSite"> 
    <patch:attribute name="linkProvider">exampleProvider</patch:attribute>
  </site>
  <site name="microSite">
    <patch:attribute name="linkProvider">exampleProvider-differentconfig</patch:attribute>
  </site>
</sites>

After making configuration changes, compile and deploy your solution.

Developer Notes

Although it should be obvious from the Sitecore configuration definitions, you can add Link Provider definitions that all use the same LinkProvider Type, or you can have definitions that use different Types. In most cases, I’ve found that there’s usually a single LinkProvider (usually Sitecore’s stock provider) but the option attributes are different between sites.

Next Steps

Make sure all Friendly URL generation flows through

Sitecore.Links.LinkManager.GetItemUrl()

This is where Sitecore inserts the SwitchingLinkManager, which allows for site-specific LinkProviders.

If you’re interested in checking out the source code, it’s available on GitHub.

Thank you to JammyKam for the essential bit of Dependency Container registration that makes custom link providers possible in Sitecore 9+.