HTML API: Add method to report depth of currently-matched element. #6589

dmsnell · 2024-05-21T01:14:13Z

The HTML Processor maintains a stack of open elements, where every element, every #text node, every HTML comment, and other node is pushed and popped while traversing the document. The "depth" of each of these nodes represents how deep that stack is where the node appears. Unfortunately this information isn't exposed to calling code, which has led different projects to attempt to calculate this value externally. This isn't always trivial, but the HTML Processor could make it so by exposing the internal knowledge in a new method.

In this patch the get_current_depth() method returns just that. Since the processor always exists within a context, the depth includes nesting from the always-present html element and also the body, since currently the HTML Processor only supports parsing in the IN BODY context.

This means that the depth reported for the DIV in <div> is 3, not 1, because its breadcrumbs path is HTML > BODY > DIV.

Fixes #61255.

github-actions · 2024-05-21T01:29:24Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

sirreal

This looks good.

sirreal · 2024-05-23T14:20:55Z

src/wp-includes/html-api/class-wp-html-processor.php

+	/**
+	 * Return how deep the currently-matched element is in the HTML document.
+	 *
+	 * @since 6.6.0
+	 *
+	 * @return int The depth of the currently-matched element.


Should we be talking about "element" here? It doesn't need to be an element we're at… should this talk about "token" or more generally "position of the processor in the document"?

I think we should say "node". These can be #text nodes here. Is "position" right? I think in places we've used "location in the document" but also in the HTML Processor I feel like we're free to talk more specifically about nodes and elements since that's what it operates on, vs. text tokens.

Node sounds good.

my own confusing is clearer now: I had un-pushed work, including the method itself. I've sent this out in d54d71f

apparently I had already chosen "of the current location" in my work, so I'm leaving it at that unless we prefer "node"

dmsnell · 2024-05-23T18:41:10Z

tests/phpunit/tests/html-api/wpHtmlProcessor.php

-			$processor->next_tag( array( 'class_name' => 'target' ) ),
+		while ( $processor->next_tag() ) {
+			if ( $processor->has_class( 'target' ) ) {
+				break;


why this change?

I thought the other form was broken, causing the test to fail. That's the only reason. I may be mistaken, feel free to revert.

oops, this is a known bug I forgot about. we claim to support class_name but don't

…epth

github-actions · 2024-05-23T23:11:25Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props dmsnell, jonsurrell.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

The HTML Processor maintains a stack of open elements, where every element, every `#text` node, every HTML comment, and other node is pushed and popped while traversing the document. The "depth" of each of these nodes represents how deep that stack is where the node appears. Unfortunately this information isn't exposed to calling code, which has led different projects to attempt to calculate this value externally. This isn't always trivial, but the HTML Processor could make it so by exposing the internal knowledge in a new method. In this patch the `get_current_depth()` method returns just that. Since the processor always exists within a context, the depth includes nesting from the always-present html element and also the body, since currently the HTML Processor only supports parsing in the IN BODY context. This means that the depth reported for the `DIV` in `<div>` is 3, not 1, because its breadcrumbs path is `HTML > BODY > DIV`. Developed in #6589 Discussed in https://core.trac.wordpress.org/ticket/61255 Fixes #61255. Props dmsnell, jonsurrell. git-svn-id: https://develop.svn.wordpress.org/trunk@58191 602fd350-edb4-49c9-b593-d223f7449a82

The HTML Processor maintains a stack of open elements, where every element, every `#text` node, every HTML comment, and other node is pushed and popped while traversing the document. The "depth" of each of these nodes represents how deep that stack is where the node appears. Unfortunately this information isn't exposed to calling code, which has led different projects to attempt to calculate this value externally. This isn't always trivial, but the HTML Processor could make it so by exposing the internal knowledge in a new method. In this patch the `get_current_depth()` method returns just that. Since the processor always exists within a context, the depth includes nesting from the always-present html element and also the body, since currently the HTML Processor only supports parsing in the IN BODY context. This means that the depth reported for the `DIV` in `<div>` is 3, not 1, because its breadcrumbs path is `HTML > BODY > DIV`. Developed in WordPress/wordpress-develop#6589 Discussed in https://core.trac.wordpress.org/ticket/61255 Fixes #61255. Props dmsnell, jonsurrell. Built from https://develop.svn.wordpress.org/trunk@58191 git-svn-id: http://core.svn.wordpress.org/trunk@57654 1a063a9b-81f0-0310-95a4-ce76da25c4cd

dmsnell · 2024-05-23T23:41:23Z

Merged in [58191]
5d52f19

The HTML Processor maintains a stack of open elements, where every element, every `#text` node, every HTML comment, and other node is pushed and popped while traversing the document. The "depth" of each of these nodes represents how deep that stack is where the node appears. Unfortunately this information isn't exposed to calling code, which has led different projects to attempt to calculate this value externally. This isn't always trivial, but the HTML Processor could make it so by exposing the internal knowledge in a new method. In this patch the `get_current_depth()` method returns just that. Since the processor always exists within a context, the depth includes nesting from the always-present html element and also the body, since currently the HTML Processor only supports parsing in the IN BODY context. This means that the depth reported for the `DIV` in `<div>` is 3, not 1, because its breadcrumbs path is `HTML > BODY > DIV`. Developed in WordPress/wordpress-develop#6589 Discussed in https://core.trac.wordpress.org/ticket/61255 Fixes #61255. Props dmsnell, jonsurrell. Built from https://develop.svn.wordpress.org/trunk@58191 git-svn-id: https://core.svn.wordpress.org/trunk@57654 1a063a9b-81f0-0310-95a4-ce76da25c4cd

HTML API: Add method to report depth of currently-matched element.

b3c6fe5

Fixes #61255.

sirreal added 3 commits May 23, 2024 16:17

Add the method

94e44a8

Fix test

a8d6c8c

Add more test cases

581872a

sirreal approved these changes May 23, 2024

View reviewed changes

Add return doc

d65d245

sirreal reviewed May 23, 2024

View reviewed changes

dmsnell commented May 23, 2024

View reviewed changes

Add get_current_depth() method.

39f9c9d

dmsnell force-pushed the html-api/add-get-depth branch from d54d71f to 39f9c9d Compare May 23, 2024 21:52

dmsnell added 3 commits May 23, 2024 15:10

Revert test to use next_tag( 'class_name' )

f95bd05

Merge remote-tracking branch 'upstream/trunk' into html-api/add-get-d…

b8cc2a0

…epth

Add non-element tests

3e41eb9

dmsnell marked this pull request as ready for review May 23, 2024 23:11

Oops, HR isn't supported.

757d133

dmsnell force-pushed the html-api/add-get-depth branch from d3be8db to 757d133 Compare May 23, 2024 23:11

Update test doc for @param

b22a825

dmsnell closed this May 23, 2024

dmsnell deleted the html-api/add-get-depth branch May 23, 2024 23:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HTML API: Add method to report depth of currently-matched element. #6589

HTML API: Add method to report depth of currently-matched element. #6589

dmsnell commented May 21, 2024 •

edited

Loading

github-actions bot commented May 21, 2024

sirreal left a comment

sirreal May 23, 2024 •

edited

Loading

dmsnell May 23, 2024

sirreal May 23, 2024

dmsnell May 23, 2024

dmsnell May 23, 2024

sirreal May 23, 2024

dmsnell May 23, 2024

github-actions bot commented May 23, 2024

dmsnell commented May 23, 2024

HTML API: Add method to report depth of currently-matched element. #6589

HTML API: Add method to report depth of currently-matched element. #6589

Conversation

dmsnell commented May 21, 2024 • edited Loading

github-actions bot commented May 21, 2024

Test using WordPress Playground

Some things to be aware of

sirreal left a comment

Choose a reason for hiding this comment

sirreal May 23, 2024 • edited Loading

Choose a reason for hiding this comment

dmsnell May 23, 2024

Choose a reason for hiding this comment

sirreal May 23, 2024

Choose a reason for hiding this comment

dmsnell May 23, 2024

Choose a reason for hiding this comment

dmsnell May 23, 2024

Choose a reason for hiding this comment

sirreal May 23, 2024

Choose a reason for hiding this comment

dmsnell May 23, 2024

Choose a reason for hiding this comment

github-actions bot commented May 23, 2024

dmsnell commented May 23, 2024

dmsnell commented May 21, 2024 •

edited

Loading

sirreal May 23, 2024 •

edited

Loading