[Breaking change]: `XPath` will be removed in Umbraco 14

Zeegaan commented 1 year ago

Description

XPath will be removed in Umbraco 14.

Version

Other (please put exact version in description textbox)

Previous behavior

You could traverse the cache as XPath with the PublishedContentQuery like so: ContentAtXPath(string xpath, params XPathVariable[] vars)

New behavior

You will no longer be able to traverse the cache using XPath.

Type of breaking change

[ ] Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
[X] Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

This does not play well when we want to implement the lady-loaded cache and when we want to use the IDistributedCache from C#.

Recommended action

Use Search methods instead

Affected APIs

INavigableContent
INavigableContentType
INavigableFieldType
INavigableSource
MacroNavigator
NavigableNavigator
RenamedRootNavigator
IPublishedContentQuery

leekelleher commented 1 year ago

Will there be an alternative way of querying for a start node on the Multi-node Tree Picker (MNTP) editor?

Zeegaan commented 1 year ago

Sorry @leekelleher not sure I'm understanding, how are you getting that right now 🤔 ?

This is change is made because of the lazy-loaded cache, and as we don't have all content in the cache, we don't think it will ever be performant to use XPath🤔

robertjf commented 1 year ago

@Zeegaan @leekelleher is referring to this:

This change won't affect this capability will it? Is there a good replacement if it does? It's very valuable to be able to specify a starting node in this way rather than choosing a specific node...

leekelleher commented 1 year ago

@Zeegaan In the configuration of MNTP, the "Node type" field as options for Content, Media, Members; and to set the start node. Which would either be a picker or an XPath query. (So you could do things like $current/ancestor-or-self::homePage/someRepository, to make the start node contextual)

Link to docs for reference: https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/multinode-treepicker#data-type-definition-example

As much as I like XPath, I'm not advocating that the codebase remains, more that, has an alternative been considered? Is there a way to have a plain-text based DSL to query hierarchical data? (Which XPath does very well, despite performance concerns).

Zeegaan commented 1 year ago

@robertjf & @leekelleher Thanks for the insight here, we will take this up internally! 💪

abjerner commented 1 year ago

Just to add to what's already been said, I think the current XPath option of the MNTP is a key feature for creating multiple sites using the same content types. AFAIK there isn't another way to dynamically set the picker root. I can imagine this will cause some headaches if removed.

prjseal commented 1 year ago

Yes I agree. It shouldn't be removed without a replacement being found for it's use in MNTP. Ideally it would be good if you could pick a node and then based on the node's type and place in the tree it work out what the search api calls should be to get to that, saving us from going back to picking specific ids or guids.

Nicholas-Westby commented 1 year ago

Regarding the XPath in the MNTP that's used to select a start node, I can imagine alternatives.

Query Builder One idea would be the query builder that I think used to (or currently is) part of the template editor. I never used this, but something like that could be used to query for a particular start node.
Visual Editor Another idea would be a visual editor that allows you to perform a sequence of operations where the prior action result servs as input to the subsequent action result, with the final action outputting the start node. Actions could include: ChildOfType, DescendantOfType, FirstChild, NthChild, and so on.
Content Finder Another idea would be to use a sort of content finder. That is, a developer would define how to find the content in a C# class, then the back office user would select that class/function in a drop down. The content finder would return the start node.

ronaldbarendse commented 1 year ago

I believe the main issue lies in the fact that the current implementation allows querying all property values, which therefore requires all property data to be available to execute the XPath query. Besides that, XPath support not been implemented correctly in all Property Value Converters since the move from the XML to NuCache, see:

We really do need a declarative way to search for content, because that's not only used in the MNTP, but also for configuring 404 pages: https://docs.umbraco.com/umbraco-cms/tutorials/custom-error-page#set-a-custom-404-page-in-appsettings.json.

Maybe we can reuse the Content Delivery API syntax for this, so you can filter by content type and name by default and use the same method to add custom filters if required: https://docs.umbraco.com/umbraco-cms/v/12.latest/reference/content-delivery-api.

bergmania commented 1 year ago

Thanks for all the input.

We totally agree there need to be an alternative for the multi node tree picker.

To my knowledge this is the only use case for XPath used by Umbraco itself and XPath still don't make sense as nothing is XML anymore, and today we have a lot of code just to partially support XPath.

Can some of you give examples of the XPath's you use today or have used in the past. So we ensure we can cover similar cases. 🙏

krebil commented 1 year ago

For multi-site setups I often use something like $site/subjectsFolder//subject to keep pickable content to the current site. It helps with reusability and narrows down the editor choices to the most relevant set of content.

But I think it's equally useful to use $current or $parent to query children of current node or siblings.

hfloyd commented 1 year ago

I agree - multi-site installs are where the XPath is most useful, or in situations where you want to allow selection of "featured" items on a category node - allowing only selections of direct descendant nodes.

greystate commented 1 year ago

Here's a couple of XPath expressions I've used:

$site/calendarContainer

$current/ancestor-or-self::website/settings[contains(@nodeName, 'Colors')]

Nicholas-Westby commented 1 year ago

Here are a few real examples:

//universalSettings
//universalSettings/enhancedCardGridFilterFolder
//universalSettings/basicCalloutFolder
//universalSettings/attributesFolder
$current/ancestor-or-self::home//central
$current/ancestor-or-self::home//central//folderFooter
$current/ancestor-or-self::home//central//folderProductSettings
$site/blogLanding
$current/ancestor-or-self::home//central//folderMenus
$parent/ancestor-or-self::FolderCentral[@level = 2]/FolderCentral[@nodeName = 'Member Locations']

greystate commented 1 year ago

Adding another one here, because it uses a pattern not used in the others:

/root/website//*[self::contentPage or self::landingPage or self::simpleLinkWidget]

timmygobang commented 1 year ago

oh my god, please don't remove this feature!!

This is a critical part of all the sites I've created for years.

It's especially useful when you run multiple sites off one Umbraco installation, and your site has a content section and a back office section. Rather than picking a node for the MNTP to start off at, I use xpath, to navigate to a node in the "back office" say a Events repository.

By removing xpath you'd effectively hard coding the starting point of a MNTP, which would ruin my set up without an alternative way of doing so in property editor.

timmygobang commented 1 year ago

There's a few reasons for using xpath

if you have multiple sites on one umbraco installation, you don't want to hard code a starting point for a multinode tree picker, you want it dynamic
when you deploy to a new env, the node id may not be the same that you've pointed it to, so the picker won't work

hfloyd commented 1 year ago

@timmygobang - Don't worry, the intention is for MNTP to still function with "dynamic" start nodes. An alternative to XPath (which is a specific XML-based technology) is in the works. See this comment, above:

Thanks for all the input.

We totally agree there need to be an alternative for the multi node tree picker.

To my knowledge this is the only use case for XPath used by Umbraco itself and XPath still don't make sense as nothing is XML anymore, and today we have a lot of code just to partially support XPath.

Can some of you give examples of the XPath's you use today or have used in the past. So we ensure we can cover similar cases. 🙏

umbraco / Announcements