Make WordPress Core

Opened 22 months ago

Closed 21 months ago

Last modified 21 months 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:


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
22 months 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
22 months 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 22 months ago by costdev (previous) (diff)

#3 @audrasjb
22 months ago

  • Keywords reporter-feedback removed

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

Version 0, edited 22 months ago by audrasjb (next)

#4 @costdev
22 months 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.


  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.

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 22 months ago by costdev (previous) (diff)

#5 @costdev
22 months 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
22 months 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.

22 months ago

  • 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
22 months 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
22 months ago

Requested changes are made and pushed.

#10 @robinwpdeveloper
22 months ago

  • Keywords changes-requested removed

@audrasjb let me know if any changes are required.

#11 @audrasjb
21 months 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
21 months ago

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