Beyond "local" for Sitecore SXA/XM Cloud
Tags: sitecore, xmcloud, sxa
Published: 2023-11-25 15:28:26

Okay, let's get one thing out of the way. Yes, it's November 25th. Yes, Sitecore MVP applications are due in a few days. Yes, folks write blog posts as a contribution. Yes, it's the last minute. Am I doing this specifically for that purpose?!?

Not really, but it doesn't hurt! Plus it's harder to put technical blogs together when I'm a project manager now.

I recently got assigned to my first XM Cloud project...yes, as a project manager, but I'm using what I know of Sitecore and the great community around it to help source information for my team. And it doesn't hurt to keep knowing enough to be dangerous. So as I gather some of these tidbits, I'll try to blog them for our reference and others.

Today is some research I was doing to set up either partial designs or page branches (a topic I'll go into in another post), and using relative references with them. To clarify, "relative" references in Sitecore are those that use SXA keywords like `local` to denote the datasource, like `local:/Data/Text 1` when you add the OOTB rich text component to a page. This is different from the traditional Sitecore datasource reference, where you see  a path but behind the scenes is the ID, to keep the content locked in even if you move it. For a relative datasource, someone could move or rename it, and it'll break the datasource. So keep that in mind!

So if you're an SXA "legacy" user, the `local` keyword is one you're familiar with. But there are others in the [Sitecore documentation](https://doc.sitecore.com/xp/en/developers/sxa/103/sitecore-experience-accelerator/use-a-prefix-to-set-the-data-source-context.html) that we don't usually think of, but could be very useful.

First is `page`, which is actually similar to `local`, in that it works relative to the item you're on. The difference comes when applying it from a partial design. On a partial, the `local` keyword will always look for the datasource local to the partial design itself, whereas `page` always looks for the datasource local to the implementation. So if you had a `page` datasource call on your partial design, anywhere you use it needs to have a datasource relative to the page it's used on. For example, if your partial has a hero component pointed to `page:Data/Hero` then every page the partial is on needs a `Data` folder with an item named `Hero`.

The other I'm finding useful is `query` as this lets you take advantage of tokens. This comes in handy if you're storing your datasources in the SXA site's `Data` folder (IE that's where you choose to store things, or the datasource is site-wide). SXA adds a `$site` token to identify what SXA site you're referring to, which you'll see used a lot in datasource locations in renderings (which sounds like another topic to expound on). But you can use it in your relative datasources too with the `query` command, like `query:$site/Data/Texts/Text 1` which will look in the site-level Data folder.

Again, remember that the datasources using these keywords are relative and can break if the item is moved or renamed, a bit more fragile than the typical datasource connection. But there's a solution for that too, if you need it. If you right-click on an item, in the *Scripts* menu there is an option for **Convert data sources to GUID** that you can use to "lock in" those content links. You can also use security to prevent users from renaming or moving items, which would handle the situation as well.