Configure URL rewriting

Current version: 19.x

To ensure that relative links in HTML are rendered properly when integrating a rendering host with advanced Sitecore editors, Headless Services rewrites relative URLs in the returned markup to be absolute. The default tags and attributes included in this processing are as follows:

Tag name

Attribute name

audio

src

img

src, srcset

link

href

script

src

source

src, srcset

track

src

video

poster, src

Disable URL Rewriting

If you do not want Headless Services to rewrite relative URLs in the returned markup into absolute URLs, you can disable URL rewriting.

To disable URL rewriting:

  • For the configured http render engine, change the value of the optionEnableRelativeLinkProcessing to false:

    RequestResponse
    <javaScriptServices>
      <renderEngines>
        <renderEngine name="http">
          <instance id="RenderEngineInstance" inherits="defaults">
            <EnableRelativeLinkProcessing>false</EnableRelativeLinkProcessing>
          </instance>
        </renderEngine>
      </renderEngines>
    </javaScriptServices>

Configure rewritten HTML attributes

You can customize URL rewrites by overriding the type Sitecore.JavaScriptServices.ViewEngine.Http.RenderEngineOptionsResolver.

To configure rewritten HTML attributes:

  1. Reference the nuget package Sitecore.JavaScriptServices.ViewEngine.Http.

  2. Create a type that inherits the type Sitecore.JavaScriptServices.ViewEngine.Http.RenderEngineOptionsResolver.

  3. Override the ResolveAll and ResolveForId.

  4. Override the LinkAttributeMap field of options returned by the base method:

    RequestResponse
        public override IEnumerable<HttpRenderEngineOptions> ResolveAll(RenderEngineOptions runtimeOptions = null)
        {
            var optionsCollection = base.ResolveAll(runtimeOptions);
            foreach (var options in optionsCollection)
            {
                options.LinkAttributeMap.Add("video", new[] { "poster", "src" });
            }
    
            return optionsCollection;
        }
    
        public override HttpRenderEngineOptions ResolveForId(string id, RenderEngineOptions runtimeOptions = null)
        {
            var options = base.ResolveForId(id, runtimeOptions);
            options.LinkAttributeMap.Add("video", new[] { "poster", "src" });
            return options;
        }
  5. Create a dependency configurator and override the IRenderEngineOptionsResolver service registration:

    RequestResponse
        public void Configure(IServiceCollection serviceCollection)
        {
            serviceCollection.AddTransient<IHttpRenderEngineFactory, HttpRenderEngineFactory>();   
            serviceCollection.AddTransient<IConfigurationReader, XmlConfigurationReader>();
            serviceCollection.AddSingleton<IHttpSessionStateResolver, HttpSessionStateResolver>();
            serviceCollection.AddTransient<IOverrideOptionsResolver, OverrideOptionsResolver>();
            serviceCollection.AddSingleton<IRenderEngineOptionsResolver, CustomRenderEngineOptionResolver>();
            serviceCollection.AddTransient<IHttpClientFactory, HttpClientFactory>();
        }   
  6. Create a config patch with the following patch:

    RequestResponse
        <services>
          <configurator patch:instead="configurator[@type='Sitecore.JavaScriptServices.ViewEngine.Http.RegisterDependencies, Sitecore.JavaScriptServices.ViewEngine.Http']" type="<CustomTypeName>, <CustomAssembly>" />
        </services>
  7. Deploy the custom assembly and configuration patch to your Sitecore instance.

Add a path to ignored paths

Some relative URL paths must not be rewritten by Headless Services. By default, these are:

  • -/media/

  • ~/media/

  • -/jssmedia/

  • ~/jssmedia/

Adding or removing paths can be done by overriding the type Sitecore.JavaScriptServices.ViewEngine.Http.RenderEngineOptionsResolver .

To add a URL path to the ignored paths:

  1. Reference the nuget package Sitecore.JavaScriptServices.ViewEngine.Http.

  2. Create a type that inherits the type Sitecore.JavaScriptServices.ViewEngine.Http.RenderEngineOptionsResolver.

  3. Override the ResolveAll and ResolveForId .

  4. Override the LinkAttributeMap field of options returned by the base method:

    RequestResponse
       public override IEnumerable<HttpRenderEngineOptions> ResolveAll(RenderEngineOptions runtimeOptions = null)
        {
            var optionsCollection = base.ResolveAll(runtimeOptions);
            foreach (var options in optionsCollection)
            {
                options.IgnoredPaths.Add("sitecore/shell/");
            }
    
            return optionsCollection;
        }
    
        public override HttpRenderEngineOptions ResolveForId(string id, RenderEngineOptions runtimeOptions = null)
        {
            var options = base.ResolveForId(id, runtimeOptions);
            options.IgnoredPaths.Add("sitecore/shell/");
            return options;
        }
  5. Create a dependency configurator and override the IRenderEngineOptionsResolver service registration:

    RequestResponse
        public void Configure(IServiceCollection serviceCollection)
        {
            serviceCollection.AddTransient<IHttpRenderEngineFactory, HttpRenderEngineFactory>();
            serviceCollection.AddTransient<IConfigurationReader, XmlConfigurationReader>();
            serviceCollection.AddSingleton<IHttpSessionStateResolver, HttpSessionStateResolver>();
            serviceCollection.AddTransient<IOverrideOptionsResolver, OverrideOptionsResolver>();
            serviceCollection.AddSingleton<IRenderEngineOptionsResolver, CustomRenderEngineOptionResolver>();
            serviceCollection.AddTransient<IHttpClientFactory, HttpClientFactory>();
        }
  6. Create a config patch with the following patch:

    RequestResponse
        <services>
          <configurator patch:instead="configurator[@type='Sitecore.JavaScriptServices.ViewEngine.Http.RegisterDependencies, Sitecore.JavaScriptServices.ViewEngine.Http']" type="<CustomTypeName>, <CustomAssembly>" />
        </services>
  7. Deploy the custom assembly and configuration patch to your Sitecore instance.

Do you have some feedback for us?

If you have suggestions for improving this article,