Build item and media URLs

Abstract

Use an API to build URLs for items and media items.

You can build the URL Sitecore uses for an item programmatically, and can build URLs for both items and media this way. You control the way the API build the URLs by using the ItemUrlBuilderOptions and MediaUrlBuilderOptions classes for item and media items, respectively. You can control things like language embedding, absolute or relative path, using display name or item name, and more.

Build an item URL

The Sitecore.Abstractions.BaseLinkManager class provides a public API to render item URLs:

public abstract string GetItemUrl(Item item, ItemUrlBuilderOptions options);

where

  • Item is the item you generate a URL for.

  • ItemUrlBuilderOptions is the specification for generating the URL.

You use the ItemUrlBuilderOptions specification to control how Sitecore builds the URL. The class extends the Sitecore.Links.UrlBuilders.UrlBuilderOptions class that contains the common properties you use to control how Sitecore generates URLs for both items and media items.

The tables below describe the properties of these two classes.

The UrlBuilderOptions class

Property

Description

bool? AlwaysIncludeServerUrl

Specifies whether the server URL is always included.

Language Language

Specifies the language. The default is Context.Language.

LanguageEmbedding? LanguageEmbedding

Specifies if and how Sitecore embeds language in the URL.

LanguageLocation? LanguageLocation

Specifies if Sitecore puts the language in the URL path or a query string.

bool? LowercaseUrls

Specifies if Sitecore renders lowercase URL.

bool? EncodeNames

Specifies if Sitecore encodes names in the URL.

bool? UseDisplayName

Specifies if Sitecore uses the display name when it generates URL.

The ItemUrlBuilderOptions class

Property

Description

bool? AddAspxExtension

Specifies if Sitecore adds the .apsx extension to the URL.

bool? SiteResolving

Specifies if Sitecore enables site resolving.

SiteContext Site

Specifies the the site.

bool? ShortenUrls

Specifies if Sitecore shortens URLs.

The default Sitecore implementation of the BaseLinkManager class uses the Sitecore.Links.LinkProvider class. The LinkProvider class uses the ItemUrlBuilder class to generate item URLs. You can inject a custom URL builder by patching the <links/itemUrlBuilder> configuration node.

The ItemUrlBuilder class has a single constructor that takes one parameter of type DefaultItemUrlBuilderOptions, the specification used by Sitecore as a fallback for null or non-provided values of the ItemUrlBuilderOptions specification.

The DefaultItemUrlBuilderOptions parameter has the same set of properties as the ItemUrlBuilderOptions options, except that these properties cannot be null.

The following example shows how you can patch the configuration:

<!-- URL BUILDERS -->
    <links>
        <urlBuilder>
            <alwaysIncludeServerUrl>false</alwaysIncludeServerUrl>
            <languageEmbedding>asNeeded</languageEmbedding>
            <languageLocation>filePath</languageLocation>
            <lowercaseUrls>false</lowercaseUrls>
            <encodeNames>true</encodeNames>
            <useDisplayName>false</useDisplayName>
        </urlBuilder>
        <itemUrlBuilder type="Sitecore.Links.UrlBuilders.ItemUrlBuilder, Sitecore.Kernel">
            <param desc="defaultOptions" type="Sitecore.Links.UrlBuilders.DefaultItemUrlBuilderOptions, Sitecore.Kernel">
                <alwaysIncludeServerUrl ref="links/urlBuilder/alwaysIncludeServerUrl" />
                <languageEmbedding ref="links/urlBuilder/languageEmbedding" />
                <languageLocation ref="links/urlBuilder/languageLocation" />
                <lowercaseUrls ref="links/urlBuilder/lowercaseUrls" />
                <encodeNames ref="links/urlBuilder/encodeNames" />
                <useDisplayName ref="links/urlBuilder/useDisplayName" />
                <addAspxExtension>false</addAspxExtension>
                <siteResolving>true</siteResolving>
                <shortenUrls>true</shortenUrls>
            </param>
        </itemUrlBuilder>
    </links>

The following table describes the configuration nodes and the value of these nodes:

Configuration node

Value

alwaysIncludeServerUrl

Specifies if Sitecore always adds the current server URL to generated URLs. The default is false.

languageEmbedding

Specifies if Sitecore embeds the language name in the URLs it generates. The options are: asNeeded | always | never. The default is asNeeded.

languageLocation

Specifies if Sitecore puts the language in the URL path or a query string. The options are filePath | queryString. The default is filePath.

lowercaseUrls

Specifies if Sitecore lowercases the URLs it generates. The default is false.

encodeNames

Specifies if Sitecore encodes the names in the URLs it generates. The default is true.

useDisplayName

Specifies if Sitecore uses the item display name. The default is false.

addAspxExtension

Specifies if Sitecore adds the .aspx extension to the URLs it generates. The default is false.

siteResolving

Specifies if Sitecore resolves site information when it renders item URLs. The default is true.

shortenUrls

Specifies if Sitecore shortens the URLs it generates. The default is true.

Example

If you have this item: /sitecore/content/home/sample item, and the item has English and Danish versions, then the following code will generate URLs similar to http://{HOST}/en/Sample Item for the English version and http://{HOST}/da/Sample Item for the Danish version:

linkManager.GetItemUrl(sampleItem, new ItemUrlBuilderOptions
                {
                    AlwaysIncludeServerUrl = true,
                    LanguageEmbedding = LanguageEmbedding.Always,
                    LanguageLocation = LanguageLocation.FilePath
                });

Build a media item URL

The Sitecore.Abstractions.BaseMediaManager class provides a public API to render media URLs:

public virtual string GetMediaUrl(MediaItem item, MediaUrlBuilderOptions options);

where

  • MediaItem is the media item you generate a URL for

  • MediaUrlBuilderOptions is the specification for generating the media URL.

You use the MediaUrlBuilderOptions specification to control the way Sitecore builds the URL. The class extends the Sitecore.Links.UrlBuilders.UrlBuilderOptions class that contains the common properties you use to control how Sitecore generates URLs for both items and media items.

The tables below describe the properties of these two classes.

The UrlBuilderOptions class

Property

Description

bool? AlwaysIncludeServerUrl

Specifies whether the server URL is always included.

Language Language

Specifies the language. The default is Context.Language.

LanguageEmbedding? LanguageEmbedding

Specifies if and how Sitecore embeds language in the URL.

LanguageLocation? LanguageLocation

Specifies if Sitecore puts the language in the URL path or a query string.

bool? LowercaseUrls

Specifies if Sitecore renders lowercase URL.

bool? EncodeNames

Specifies if Sitecore encodes names in the URL.

bool? UseDisplayName

Specifies if Sitecore uses the display name when it generates URL.

The MediaUrlBuilderOptions class

Property

Description

bool? AbsolutePath

Specifies if Sitecore renders a media link with an absolute path.

bool? AllowStretch

Specifies if Sitecore allows the media to be stretched as it is rendered.

bool? AlwaysAppendRevision

Specifies if Sitecore always appends the media item revision.

bool? DisableBrowserCache

Specifies if Sitecore sets a header values that prevents the browser from caching the media item.

bool? DisableMediaCache

Specifies if Sitecore sets a property that prevents the browser from caching the media item in the media cache.

bool? IgnoreAspectRatio

Specifies if Sitecore ignores the aspect ratio when resizing media.

bool? IncludeExtension

Specifies if Sitecore includes an extension in the URL. it generates.

bool? Thumbnail

Specifies if the media item is a thumbnail.

bool? UseDefaultIcon

Specifies if Sitecore uses the default icon for the media item.

bool? UseItemPath

Specifies if Sitecore uses the item path when it builds a media URL.

int? Height

Specifies the height of the media item.

int? MaxHeight

Specifies the maximum height of the media item.

int? Width

Specifies the width of the media item.

int? MaxWidth

Specifies the maximum width of the media item.

float? Scale

Specifies the scale of the media item.

string DefaultIcon

Specifies the default icon.

string RequestExtension

Specifies the request media extension.

string VirtualFolder

Specifies the virtual folder of the media item.

string ItemRevision

Specifies the item revision of the media item.

Color? BackgroundColor

Specifies the background color.

Example

If you have a media item: /sitecore/media library/Images/myImage, then the following code generates a URL similar to http://{HOST}/-/media/Images/myImage.ashx?bc=White&amp;h=300&amp;w=200:

mediaManager.GetMediaUrl(mediaItem, new MediaUrlBuilderOptions
                {
                    AlwaysIncludeServerUrl = true,
                    BackgroundColor = Color.White,
                    Height = 300,
                    Width = 200
                });