Edit

URLs and tokens in SharePoint

  • Article

Learn how to formulate URLs and how to use URL tokens in SharePoint.

Types of URLs in SharePoint

SharePoint parses URL strings to determine the form of URL based on a specified protocol (for example, http:) or on the placement of a forward slash (/) within the string. Depending on the particular member, you can use the following URL forms:

  • An absolute URL specifies a full path and begins with a protocol. For example, http:// domain_or_server/[ sites/] Web_Site/ Lists/ List_Title/ AllItems.aspx.

  • A domain-relative URL is based on the domain (which might be the name of a server) address and always begins with a forward slash. It specifies a complete path from top-level website to file name. For example, /[ sites/] Web_Site/ Lists/ List_Title/ AllItems.aspx.

  • A website-relative URL is based on the address of a website object ( SPWeb ). It does not begin with a forward slash, and it specifies a complete path from the website address to the file name. For example, Lists/ List_Title/ AllItems.aspx.

  • A URL relative to a file or folder is based on the folder containing the file. It does not contain any forward slashes. It simply specifies the name of the file. For example, AllItems.aspx.

Note

There is no concept of a "site collection-relative URL"; passing such a URL may cause the code to fail.

Good practice for image URLs

When you create a URL to an image file that is located in the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS\1033\IMAGES directory, specify a path that uses the root website of the site collection, but that does not include a subsite within the path. For example, use /_layouts/images/MyImage.gif for an image file, not /MySubsite/_layouts/images/MyImage.gif. This is because subsite URLs are resolved in different ways depending on where they are used. You can ignore these variations if you always use the root website-relative URL.

URL tokens in SharePoint

SharePoint supports the tokens listed in the following tables for use in either SharePoint Add-ins or farm solutions. In addition, some tokens are usable only in apps. For more information about them, see URL strings and tokens in SharePoint Add-ins.

The tokens in the tables of this section can be used in URLs in a wide variety of situations in SharePoint development, such as in custom actions and in links on custom pages. In some contexts, some of these tokens cannot be used. Three of the most important places where only a restricted list of tokens can be used are the start page of an app, a custom action on the host web, and the Src property of an app part. These are called out in separate columns, but these three are not an exhaustive list of places where tokens can be used.

The StartPage column specifies whether the token can be used in the StartPage element of an app manifest. The Custom Action column specifies whether the token can be used in the URL of a custom action on a host web. The App Part column specifies whether the token can be used in the Src property of the app part.

Tokens that can be used at the beginning of a URL

Token Resolves to StartPage Custom Action App Part Remarks
~controlTemplates
The URL of the ControlTemplates virtual folder for the current website.
No
No
No
~layouts
The URL of the Layouts virtual folder for the current website.
No
No
No
~site
The URL of the current website.
No
No
Yes
~sitecollection
The URL of the parent site collection of the current website.
No
No
Yes

Except where indicated otherwise, none of these tokens in the next table can be used in the path portion of the Src property value of the app part. The App Part column refers to their use in the query string portion of the value.

Tokens that can be used inside a URL

Token Resolves to StartPage Custom Action App Part Remarks
{ControlTemplates}
The URL of the ControlTemplates virtual folder for the current website.
No
No
No
{ItemId}
The ID of an item in a list or library (an integer).
No
Yes
No
{ItemUrl}
The URL of the item being acted upon.
No
Yes
No
{Layouts}
The URL of the Layouts virtual folder for the current website.
No
No
No
{ListId}
The ID of the current list (a GUID).
No
Yes
No
{RecurrenceId}
The recurrence index of a recurring event.
No
Yes
No
This token is not supported for use in the context menus of list items.
{Site}
The URL of the current website.
No
Yes
Yes
{SiteCollection}
The URL of the parent site of the current website.
No
Yes
Yes
{SiteUrl}
The URL of the current website.
No
Yes
No
{Source}
The HTTP Request URL.
No
Yes
No

See also