Skip Navigation

[Resolved] Is page template file required for layouts to be listed in page editor?

This is the technical support forum for Toolset - a suite of plugins for developing WordPress sites without writing PHP.

Everyone can read this forum, but only Toolset clients can post in it. Toolset support works 6 days per week, 19 hours per day.

This topic contains 7 replies, has 2 voices.

Last updated by Kirill 5 years, 2 months ago.

Assigned support staff: Minesh.


The theme I'm building has an index.php file that include a code like this:

if (defined( 'WPDDL_VERSION' )) :
	the_ddlayout( 'default-layout' );

I also created several layouts to be used as page templates.

However, when I open a page in a page editor, those layouts I created are not listed, only template files are shown. Please see the first screenshot.

However, once I create a page template file (page.php) with the following code (borrowed from the starter theme):

if ( defined( 'WPDDL_VERSION' ) ) :
	the_ddlayout( 'page-default' ); 
	get_footer( );

then my layouts stated to appear in the list.

Does it mean I HAVE to have a page.php template in my theme? I would prefer to have just index.php that will show all types of content, if possible.

I also noticed that a starter theme uses different arguments for the_ddlayout() calls. What do they mean? Is it documented anywhere? Before, I believe, it did not matter what arguments were because the assigned layout will always be shown. Is there a change here?



Languages: English (English )

Timezone: Asia/Kolkata (GMT+05:30)

Hello and thank you for contacting Toolset support.

I believe you should refer to the following link that may help you to understand how you should edit your theme files and clear your doubts.

Please refer to the following syntax:

the_ddlayout( 'YOUR-DEFAULT-LAYOUT-FOR-THIS-TEMPLATE-SLUG-OR-ID', array('post-content-callback' => 'A-CALLBACK-FUNCTION-AS-FALLBACK-FOR-POST-CONTENT-IF-YOU-WANT', 'allow_overrides' => 'false') );

The 'allow_overrides' parameter set to false forces the layout given as an argument to be rendered for that particular template.


Hi Minesh!

Thank you for this additional information you've provided and sorry for my late response: I was very busy lately.

I did some tests with a Toolset Starter theme and still think it does not work exactly as it should. Please try to reproduce the issue according to description below, if possible, and let me know what do you think.

Toolset Starter provides five templates: index.php, single.php, page.php, 404.php, and image.php.
For a page, page.php is a default template, and this is correct. When a page is opened in a post editor, all layouts that exist in a system are shown as available to be assigned to this page (this is correct).

Now remove page.php template from the theme's directory. According to WordPress template hierarchy (please see, index.php template should be used now instead of page.php.

However, in post editor no layouts are shown by default for a page, like if there is no default template for it. This is incorrect, because there is a valid index.php template provided by a theme. When "Show all templates" option is chosen, all layouts are shown with "in Reference Single" postfix (which mean to use single.php layout). If any of those layouts be assigned to a page, the page is shown using single.php template.

This is incorrect, according to WordPress hierarchy index.php layout should be used instead, not single.php. Single.php should be used for posts, and never for pages.

Could you please explain my why is it working this way? To me it seems that Toolset redefines WordPress template hierarchy, and this is a very wrong thing to do, I believe.

Thank you in advance!



Languages: English (English )

Timezone: Asia/Kolkata (GMT+05:30)

I think here you have confusion with two different things:
- the template hierarchy
- custom templates for pages you can select manually with the template selector

1. the template hierarchy is how wordpress loads templates for any kind of resource automatically depending on the query string and this is working with the rules for which you send me a link where whole template hierarchy is defined.

2. templates listed in the template sector are the ones with the special comment header which is it self a custom template.
For example:

 * Template Name: Layouts page template

they DO not respond to the template hierarchy, on the contrary they override it for all the post types marked as hierarchical in their definition.
if a post type is hierarchical in its post edit page the template selector is shown and all the custom templates are listed there:

You can see more information about the custom page templates on following link:

Hope this helps to eliminate your doubts.


Hi Minesh!

I don't have a problem with how WordPress templates work. If I disable Layouts plug-in, everything works as you've described: default template hierarchy is applied by default, and it can be overriden by templates with "Template Name: XXX" string specified.

I do not, however, understand fully the logic behind Layout Template names displayed in "Template and Layout" section of Page Attributes. I will attach screenshots to make it more clear. When I open a page to edit in a post editor:

1. If page.php template is present. In this case "Template and Layouts" shows all available Layout Templates (see screenshot 1). If I choose any Layout Template from the list, it will display a page using page.php WordPress template. So Layout decides that page.php is a default WordPress template for pages. This seems to be correct.

2. page.php is removed. In this case "Template and Layouts" shows no Layout Templates by default (see screenshot 2). Why is it so? There is no page.php template, but the next one in hierarchy is index.php. On my opinion, all available templates should be shown because there is index.php, and, if chosen, selected Layout Template should be shown using index.php WordPress template.

It looks to me that Layout thinks that page.php "fits" to be a default layout for a page, and index.php does not.

Why do I want to know all those fancy details? Because I'm creating a theme, and I want it to show all available layouts for every available post type. And I need to understand what WordPress templates should I have for that. Can I have just one index.php that will handle posts/ pages/ etc. using conditional logic or do I need to have the whole set of index.php, page.php, single.php, etc. and duplicate some code.

I just want my clients to have a consistent experience.



Languages: English (English )

Timezone: Asia/Kolkata (GMT+05:30)

Please allow me to consult our developers for this and I'll get in touch with you as soon as possible.



Languages: English (English )

Timezone: Asia/Kolkata (GMT+05:30)

since Layouts 1.2 layouts gives precedence to page.php this is by design and how it should be intended to work.

BUT if you create other Layouts templates you have a "Show all templates" option by pressing it it shows all the templates and all the associations Layouts + php Template so you can select the one you want to use.

Please refer attached image for more reference. Does this help you to eliminate your doubt?


Hi Minesh!

Thank you for the explanation! Now I understand that page.php actually do have a priority and this is by design. So, I guess, it's better to have page.php for users to avoid hitting "Show all templates" which can be confusing.

BTW, it works differently with posts. If there is a single.php, it is used as a default layout. If not, index.php is used instead. This is how it differs from pages.

Best regards,