WordPress.org
Get WordPress

Make WordPress Core

Opened 2 years ago

Closed 2 years ago

Last modified 2 years ago

#56394 closed defect (bug) (fixed)

Add docs to clarify that `get_page_template()` doesn't work on block themes

Reported by: audrasjb's profile audrasjb Owned by: audrasjb's profile audrasjb
Milestone: 6.1 Priority: normal
Severity: normal Version: 5.9
Component: Editor Keywords: has-patch add-to-field-guide
Focuses: docs Cc:

Description

As of today, get_page_template() doesn't work on block based themes, and it should be documented accordingly in the docblock of this function.

For example, the following sample snippet can be used in the functions.php file of any theme. It outputs the value returned by get_page_template() right after <body> opening tag.

function test_get_template_page() {
	$template = get_page_template();
	echo '<div style="position: absolute; top: 20px; width: 100%; padding: 1em; background: #fff; color: #000;">' . $template . '</div>';
}
add_action( 'wp_body_open', 'test_get_template_page' );

It always return my-website/wp-includes/template-canvas.php on a block theme. This backward compatibility issue should be documented accordingly.

Change History (13)

#1 @audrasjb
2 years ago

Note: this ticket was opened after a User Contributed Note by @thomask on DevHub, so this contributor needs to be credited by a props when a patch for this ticket if committed.

#2 @costdev
2 years ago

  • Keywords reporter-feedback added

Is this the intended behaviour?

​get_page_template() returns from ​get_query_template(), which calls ​locate_block_template(). That suggests to me there should be a path in which a block template can be retrieved, and that this may be a defect (bug).

Last edited 2 years ago by costdev (previous) (diff)

#3 @audrasjb
2 years ago

  • Keywords reporter-feedback removed

Indeed, the best option would be to return the current template, of course, but to be honest, I didn't even check the current implementation. It would makes sense to me 👍

Last edited 2 years ago by audrasjb (previous) (diff)

#4 @costdev
2 years ago

I took a deeper look at the implementation.

TL;DR - Yep, it's a design decision and so a docs-only issue. The snippet below is a way I was able to retrieve what I expected - but it's private.

locate_block_template():

  1. Sets the $_wp_current_template_content global to the contents of the block template and returns wp-includes/template-canvas.php.
  2. wp-includes/template-canvas.php calls get_the_block_template_html().
  3. get_the_block_template_html() makes use of the $_wp_current_template_content global variable and returns the generated template markup.

So get_page_template() does work for block themes in providing a template that will be populated with the correct markup. However, it does not return the actual block template being used.

This seems to achieve the goal of getting the actual .html file.

<?php
function get_the_page_template() {
        $file = _get_block_template_file( 'wp_template', get_page_template_slug() );
        var_dump( $file['path'] );
}
add_action( 'wp_body_open', 'get_the_page_template' );

Unfortunately, as the _ signifies private access, we couldn't consider _get_block_template_file() as a recommended public alternative as it's subject to change.

Last edited 2 years ago by costdev (previous) (diff)

#5 @costdev
2 years ago

Looking at ​the return for locate_block_template(), this may be a good reference for a docs change for get_page_template().

#6 @audrasjb
2 years ago

Yeah I think we should at least go with a mention to rather use locate_block_template() for block themes.

This ticket was mentioned in ​PR #3145 on ​WordPress/wordpress-develop by ​robinwpdeveloper.
2 years ago #7

  • Keywords has-patch added; needs-patch removed

Doc block added for the function get_page_template. This function is discouraged to use for block themes. Rather use locate_block_template function.

Trac ticket: 56394

#8 @audrasjb
2 years ago

  • Keywords changes-requested added

Thanks for the PR @robinwpdeveloper. I think we should probably use the docblock long description for this recommendation (see the comment added to your PR) :)

#9 @robinwpdeveloper
2 years ago

Requested changes are made and pushed.

#10 @robinwpdeveloper
2 years ago

  • Keywords changes-requested removed

@audrasjb let me know if any changes are required.

#11 @audrasjb
2 years ago

  • Owner set to audrasjb
  • Resolution set to fixed
  • Status changed from new to closed

In 54179:

Docs: Clarify that get_page_template() doesn't work on block themes.

When working on a block theme, locate_block_template() should be used instead of get_page_template(). This changeset updates the docblock of this function accordingly.

Props audrasjb, costdev, robinwpdeveloper.
Fixes #56394.
See #55646.

#13 @milana_cap
2 years ago

  • Keywords add-to-field-guide added
Note: See TracTickets for help on using tickets.