Use a prefix to set the data source context

Current version: 9.3

Most SXA renderings are designed for reusability and pull data from data source items. This means that the content they display is not bound to the page on which they appear but is stored in data source items. A component data source is the item that you set on a component to define where the content is pulled from for that component.

SXA provides several ways to assign a data source to a component. You can use a query to determine the data source context, run a source field report to set the data source context, but you can also use prefixes to determine the data source context.

Pull the data source from a field

To pull the component data source from a field:

  • Use the following prefix:

    Prefix

    field:<field name>

    Example

    field:Title

If you use a field name from a context item as the data source, SXA does the following:

  • If the field type is a link field, then SXA uses the target item ID as a data source.

  • If the field type is not a link field, and the field value is not empty, then SXA uses the field raw value as a data source.

This can be convenient when, for example, you have a product detail page that uses a partial design and you want a component in the partial design to pick the content from the product item field itself.

Specify a data source relative to the page

Instead of specifying the full path of the item, you can use a special notation to make that path relative to the context item. SXA converts the relative path to a full item path when the page is rendered.

This can be convenient for reusable page elements, for example, in partial designs when you want to store the data underneath each page rather than taking it from a global location.

To specify the data source relative to the page, use the page and local prefixes:

Prefix

page:<relativepath>

local:<relativepath>

Example

page:/blog1

local:/data/text1

For items with dashes, use hashtags. For example:

page:/#my-test-blog#

SXA uses the page: notation for components stored underneath a page in the page data folder. In many cases, the page: and local: notation give you the same result. When used in partial designs, the local: notation results in items taken from under that partial design whereas the page: forces SXA to always look for the data source under the page.

Resolve the data source using code

To resolve the data source using code:

  1. Create a custom class that implements Sitecore.Buckets.FieldTypes.IDataSource. This interface contains a single method named ListQuery:

    Item[] ListQuery(Sitecore.Data.Items.Item item)

  2. To apply the code, use the following prefix:

    Prefix

    code:<full class name>

    Example

    code:SXA.POC.DataSources.CodeDataSource,SXA.POC

This method lets you get an array of items that you want to use for your data source. The item passed to Sitecore will be the item that your code returns. If you are using this to set the data source of a component, this will be its Context.Item. Your code is invoked in the resolveRenderingDatasource pipeline processor.

This can be convenient when you want to return different items, for example, based on the time of the day or other business-specific criteria.

You use the content search queries to retrieve Sitecore items. You can restrict the items that the component retrieves by providing narrowing criteria for your search query.

This can be convenient when you want to use SXA dynamic query tokens or when you want to pick the data source item based on one of its facets.

Prefix

Sitecore content search query

Example

template:{57bcf1ce-35cb-4752-b23b-2d4522af6292};location:{85C181E3-3C5C-4591-9634-F7A90AFDCAA0}

Retrieve the data source with Sitecore query

You can use Sitecore queries to retrieve Sitecore items. You can use standard Sitecore query notation including filtering.

This can be convenient when you want to dynamically populate the data source with items based on their item tree location.

Do you have some feedback for us?

If you have suggestions for improving this article,