Get to Know the IncludeServerUrlInMediaUrls Feature in Sitecore Layout Service

·

3 min read

The Sitecore.LayoutService.Jss.config file contains a configuration for the IncludeServerUrlInMediaUrls setting, which determines whether the server URL is included in media URLs. In this article, I will explore the purpose and impact of IncludeServerUrlInMediaUrls, examining how it influences the inclusion or exclusion of the server URL in media URLs. Join me as we uncover the inner workings of this setting and understand its implications for your Sitecore implementation.

Default Contents Resolver

Navigate to Sitecore.LayoutService.Jss.config to find the following configuration:

        <config name="jss">
          <rendering type="Sitecore.LayoutService.Configuration.DefaultRenderingConfiguration, Sitecore.LayoutService">
            <placeholdersResolver type="Sitecore.LayoutService.Placeholders.DynamicPlaceholdersResolver, Sitecore.LayoutService" />
            <itemSerializer type="Sitecore.JavaScriptServices.ViewEngine.LayoutService.JssItemSerializer, Sitecore.JavaScriptServices.ViewEngine" resolve="true">
              <AlwaysIncludeEmptyFields>true</AlwaysIncludeEmptyFields>
            </itemSerializer>
            <renderingContentsResolver type="Sitecore.LayoutService.ItemRendering.ContentsResolvers.RenderingContentsResolver, Sitecore.LayoutService">
              <IncludeServerUrlInMediaUrls>true</IncludeServerUrlInMediaUrls>
            </renderingContentsResolver>
          </rendering>
          <serialization type="Sitecore.JavaScriptServices.ViewEngine.LayoutService.SerializationConfiguration, Sitecore.JavaScriptServices.ViewEngine">
            <transformer type="Sitecore.JavaScriptServices.ViewEngine.LayoutService.Serialization.LayoutTransformer, Sitecore.JavaScriptServices.ViewEngine" resolve="true" />
          </serialization>
        </config>

When the IncludeServerUrlInMediaUrls is set as true, the layout service API (/sitecore/api/layout/render/jss) will include the server URL (myproject.cm) in the media URLs. Change this setting to false to get the relative paths only.

This configuration is used by the ProcessItem method in the Sitecore.LayoutService.ItemRendering.ContentsResolvers.RenderingContentsResolver class:

protected virtual JObject ProcessItem(Item item, Rendering rendering, IRenderingConfiguration renderingConfig)
{
    Assert.ArgumentNotNull(item, "item");
    using (new SettingsSwitcher("Media.AlwaysIncludeServerUrl", IncludeServerUrlInMediaUrls.ToString()))
    {
        return JObject.Parse(renderingConfig.ItemSerializer.Serialize(item));
    }
}

A solution can have multiple layout service endpoints and each endpoint has its configuration for the IncludeServerUrlInMediaUrls setting. For example:

<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <layoutService>
      <configurations>
        <config name="jss">
            <renderingContentsResolver type="Sitecore.LayoutService.ItemRendering.ContentsResolvers.RenderingContentsResolver, Sitecore.LayoutService">
              <IncludeServerUrlInMediaUrls>false</IncludeServerUrlInMediaUrls>
            </renderingContentsResolver>
          </rendering>
        </config>
        <config name="jss-rendering">
            <renderingContentsResolver type="Sitecore.LayoutService.ItemRendering.ContentsResolvers.RenderingContentsResolver, Sitecore.LayoutService">
              <IncludeServerUrlInMediaUrls>true</IncludeServerUrlInMediaUrls>
            </renderingContentsResolver>
        </config>
      </configurations>
    </layoutService>
  </sitecore>
</configuration>

Each endpoint has a unique identified name (default, jss or jss-rendering). It is possible to configure different applications to use different layout service endpoints.

default:

https://myproject.cm/sitecore/api/layout/render?item=/&sc_apikey=

jss:

https://myproject.cm/sitecore/api/layout/render/jss?item=/&sc_apikey=

jss-rendering:

https://myproject.cm/sitecore/api/layout/render/jss-rendering?item=/&sc_apikey=

Custom Contents Resolver

When you create a custom contents resolver, you can also configure the IncludeServerUrlInMediaUrls for that custom contents resolver. A custom contents resolver inheriting the functionality of RenderingContentsResolver class gives you access to the IncludeServerUrlInMediaUrls property. This property can be used to construct the MediaUrlBuilderOptions for the MediaManager.GetMediaUrl method.

public class FeaturedListContentsResolver : RenderingContentsResolver
{
    private readonly BaseLinkManager _linkManager;

    public FeaturedListContentsResolver(BaseLinkManager linkManager)
    {
        _linkManager = linkManager;
    }

    public override object ResolveContents(Rendering rendering, IRenderingConfiguration renderingConfig)
    {
        var contextItem = GetContextItem(rendering, renderingConfig);

        MultilistField articles = contextItem.Fields["Articles"];

        return new
        {
            Articles = articles.GetItems().Select(i =>
            {
                ImageField imageField = i.Fields["image"];
                var mediaUrl = "";

                if (imageField != null && imageField.MediaItem != null)
                {
                    MediaItem mediaItem = new MediaItem(imageField.MediaItem);
                    mediaUrl = MediaManager.GetMediaUrl(mediaItem, new MediaUrlBuilderOptions { AlwaysIncludeServerUrl = IncludeServerUrlInMediaUrls });
                }

                DateField dateField = i.Fields["date"];
                var date = dateField.DateTime;

                return new
                {
                    Title = i["Title"],
                    Url = _linkManager.GetItemUrl(i),
                    Summary = i["Summary"],
                    Image = mediaUrl,
                    Date = date
                };
            })
        };
    }
}

The value of the IncludeServerUrlInMediaUrls property can be changed in the Content Editor:

If the MediaManager.GetMediaUrl is called without the MediaUrlBuilderOptions instead, the default <urlBuilder> setting in the Sitecore.config will be used.

<urlBuilder>
  <alwaysIncludeServerUrl>false</alwaysIncludeServerUrl>
</urlBuilder>

In conclusion, the IncludeServerUrlInMediaUrls setting holds substantial significance in Sitecore development. Understanding its functionality and implications is crucial for ensuring seamless content delivery and user experiences. By grasping the intricacies of this configuration, developers can effectively control the inclusion or exclusion of the server URL in media URLs. Stay tuned for more insights and tips as I continue to explore the depths of Sitecore and empower you with the knowledge to optimize your implementations.