Add available page templates REST field and selector to sidebar

[westonruter]

See #991.

• Add endpoint for returning the available page templates for a given page, along with their names for displaying in the UI. (There is another PR open for REST API extensions in Add user preference api #1948.) This should get merged into core with the Gutenberg code serving as a polyfill.
• Add page template selector to sidebar, following up on Add page attributes menu order to sidebar #1957.

Note that the reason for adding an entire new field on the page resource is explained in #991 (comment). The page templates available for a page can vary from page to page due to the theme_{$post_type}_templates filter which is passed the page instance. This is the reason for adding a new field to the page itself. Note also that the list of page templates is already exposed on in the schema:

                "template": {
                    "required": false,
                    "enum": [
                        "page-without-comments.php",
                        "page-without-footer.php",
                        "page-without-sidebar.php",
                        ""
                    ],
                    "description": "The theme file to use to display the object.",
                    "type": "string"
                }

However, the name of the template is not included. Therefore, the names are then included in this new field:

    "available_page_templates": [
        {
            "name": "No Comments",
            "template": "page-without-comments.php"
        },
        {
            "name": "No Footer",
            "template": "page-without-footer.php"
        },
        {
            "name": "No Sidebar",
            "template": "page-without-sidebar.php"
        }
    ],

[nylen]

I used this PR to tweak the codecov settings so that it won't leave comments for PRs that don't change test coverage. (Right now, test coverage is only measured for JS code; separately, we should look into making codecov measure both JS and PHP coverage.)

[nylen]

The code here seems like the most straightforward path towards exposing this information about page templates. However, I think some of it (the relationship between page templates and names, at least) might be a better fit for a theme endpoint.

#991 (comment) mentions the page_attributes_dropdown_pages_args filter, and this PR mentions theme_{$post_type}_templates instead. Are both of these filters used to modify the list of page templates per page? How common actually is this?

If not for these filters, or if they are almost never used, then I would say the list of page templates is really a property of the active theme. Unfortunately, there's not yet a great place to expose information like that in the REST API, so taking it onto the page endpoints may still make the most sense for now.

[westonruter]

991 (comment) mentions the page_attributes_dropdown_pages_args filter

That was a typo on my part. I should have said theme_{$post_type}_templates.

Are both of these filters used to modify the list of page templates per page?

It's interesting to note that not only can theme_{$post_type}_templates reduce the number of templates that are available to a given page, but it also allows the names of the templates to vary by the given page. Also, there may be page templates that are exposed for one specific page which are not in the global list of templates returned by wp_get_theme()->get_page_templates(). In way, the enum currently used for this field I think is incorrect. You can see from wp_insert_post() that it gets all of the available templates for a given page, and then it verifies that the incoming template is among those for that post: https://github.com/WordPress/wordpress-develop/blob/0ac2a97aaddd7d36401f5f42bd529ba1610cb984/src/wp-includes/post.php#L3413-L3422

Imagine the usefulness of having a list of front-page templates which are shown only for the page that is shown on front, and these same templates are not available for other pages. These can be accomplished via the theme_{$post_type}_templates filter, including PHP templates even that lack the Template Name meta.

How common actually is this?

I don't know 😄 I'll run an ack with the theme/plugin slurpers to find out.

[westonruter]

@nylen there are 43 instances of this filter being used in themes and plugins: https://gist.github.com/westonruter/629aa2e2fd0eb74f70d6c3bfea92071f

Some plugins that stand out to me which use the filter include: elementor, eventbrite-api, woocommerce.

[youknowriad]

Dropping a note here after a discussion in Slack.

What's the difference between theme templates and other theme options like color palette, wide-image setting. I tend to see those as just another theme setting. It just have a different way to declare this setting.

So for now, we're using a config variable provided to the editor on init, we could use the same variable to provide the available templates.

Having an endpoint for the theme settings makes sense too but I'd think it has to include several theme settings and not only the available templates.

[nylen]

As noted above, I'm not a big fan of the data model here. I still think page template should be a property of a theme, and we should (separately) evaluate whether it's possible to get a list of all the available templates for a theme. If possible, listing all available templates, then occasionally failing to set the template with an error message like "This template is not available for this page" seems ok to me.

Still, that's a much larger exploration, likely as part of a set of theme endpoints. So I think for now there are a couple of different options:

1. Go with the register_rest_field( 'page', 'available_page_templates', ) change in this PR, and seek to revisit how it works later on.
2. As Riad suggests above, pass information about page templates as a "side channel" data item, without using the REST API.

Given that we know the data model here isn't great, and we don't actually need to call out to the REST API and update this information beyond loading the initial content, I'm kind of leaning towards the second option, but would be interested in hearing about any drawbacks.

[westonruter]

we should (separately) evaluate whether it's possible to get a list of all the available templates for a theme

I don't think this is possible since a plugin could supply any PHP file as being a page template for a specific page. In other words, there wouldn't be a way to get a lost of all possible templates without applying the filters on every page created in the DB and getting the combined set of all.

As Riad suggests above, pass information about page templates as a "side channel" data item, without using the REST API.

Yes, bypassing the REST API and exporting the available page templates for the given page among in the initial PHP exports makes sense to me.

[westonruter]

Closing this because @nylen's out-of-REST-API-band approach will work better.