Routing

The Episerver Commerce routing system extends the Episerver CMS Routing system to expose catalog content like products, variations and categories, using individual URLs. The actual data sent to the client browser is then compiled by a matching render template. See Commerce rendering templates for information about rendering. Categories have their own URL and can have their own rendering template, for instance to display a product listing.

Catalog content URLs have two forms:

• Hierarchical URL. In the form domain/language/catalog/category/product following the structure of the catalog. For example, mysite.com/en/wine/accessories/corkscrew.
• Simple address/SEO URL. A single segment uniquely identifying content and its language. For example, mysite.com/professional-corkscrew-en.aspx.

The SEO URL field has been part of the catalog information since previous versions of Episerver Commerce. But with the new routing, it works the same way as the Episerver CMS "Simple address" concept. Hence, you may see both terms used.

Registering routes

To enable routing to catalog content, register the catalog partial router in an EPiServer.Framework.IInitializableModule using the CatalogRouteHelper.

using System.Web.Routing;
using EPiServer.Framework;
using EPiServer.Commerce.Routing;
using EPiServer.Framework.Initialization;

namespace CodeSamples.EPiServer.Commerce.Catalog
{
    [ModuleDependency(typeof(global::EPiServer.Commerce.Initialization.InitializationModule))]
    public class RegisterRoutingModuleSample : IInitializableModule
    {
        public void Initialize(InitializationEngine context)
        {
            MapRoutes(RouteTable.Routes);
        }

        private static void MapRoutes(RouteCollection routes)
        {
            CatalogRouteHelper.MapDefaultHierarchialRouter(routes, true);
        }

        public void Uninitialize(InitializationEngine context) { /*uninitialize*/}

        public void Preload(string[] parameters) { }
    }
}

Outgoing routes

Outgoing routes are used when rendering links in the template. For example, using the Html.ContentLink helper (ASP.NET MVC), the EPiServer.Web.Routing.UrlResolver class or links are added to an Xhtml property by an editor. Commerce routes also register an outgoing route, which is determined by the flag passed to CatalogRouteHelper in the initialization:

• CatalogRouteHelper.MapDefaultHierarchialRouter(routes, false) uses hierarchical links.
• CatalogRouteHelper.MapDefaultHierarchialRouter(routes, true) uses the SEO URL in links.

Working with hierarchical URLs

Hierarchical URLs are constructed using the Name in URL property of each content instance in the hierarchy, leading to the requested content. The first segment is the catalog, followed by any categories and subcategories down to the target category, product, variation, and so on. To determine the language, either a language segment (for example, "en/") is prepended, or the configured site host mapping is used (see Globalization scenarios for more information about site host mapping).

The Name in URL property value is automatically generated from the Name when new content is created. Because only certain characters are valid in a URL and because the Name in URL needs to be unique in the catalog, it may not match the Name. A unique value is added at the end of the Name in Url if other content in the catalog has the same Name in Url as the Name of the new content. You can edit Name in URL to take any valid value -- it does not have to be similar to the Name.

Working with SEO URLs

SEO URLs are stored in the SEO URL property and should be unique across all catalogs and languages, which is why only one segment is needed to identify the requested content. It also means that the URL is unaffected by moving the product in the catalog tree, or changing the Name in address of a content somewhere above in the hierarchy.

The SEO URL property value is automatically generated from the Name when content is created. For additional language versions, the language code is appended to make the SEO URL unique. Because only certain characters are valid in a URL and because the SEO URL needs to be unique across all catalogs, it may not match the Name. By default, an .aspx extension is used, but the SEO URL can of course be edited to take any valid value and does not have to be similar to the Name or include any extension.

Changing the default generation of SEO Url, and name in url

The class UniqueSeoGenerator will be called when a seo url or uri segment (name in url) will be created. This logic can be overridden by inheriting from UniqueSeoGenerator and overridding GenerateSeoUri and/or GenerateUriSegment. The custom unique seo generator will then have to be registrated in an initialization module.

public class ExntedUniqueSeoGenerator : UniqueSeoGenerator
{
    protected override string UriExtension
    {
        get
        {
            return ".html";
        }
    }

    public override string GenerateSeoUri(string name, string languageCode, bool includeRandomToken)
    {
        return includeRandomToken
            ? String.Format("{0}_{1}_{2}{3}", CommerceHelper.CleanUrlField(name), languageCode, GetRandomToken(), UriExtension)
            : String.Format("{0}_{1}{2}", CommerceHelper.CleanUrlField(name), languageCode, UriExtension);
    }

    public override string GenerateUriSegment(string name, bool includeRandomToken)
    {
        return includeRandomToken
            ? String.Format("{0}_{1}", UrlSegment.GetUrlFriendlySegment(name), GetRandomToken())
            : UrlSegment.GetUrlFriendlySegment(name);
    }

    protected override string GetRandomToken()
    {
        var chars = "abcdefghijklmnopqrstuvwzyz1234567890";
        var random = new Random();
        var result = new string(
            Enumerable.Repeat(chars, 8)
                        .Select(s => s[random.Next(s.Length)])
                        .ToArray());

        return result;
    }
}

Related topics

• Routing in the CMS Developer Guide
• Commerce rendering templates