Broken theme error message is very confusing

[mayukojpn]

When we start creating child theme, we should have a stylesheet and a template tag within it.

If we forget to include template tag (it means parent theme name in style.css) and try to activate it, WordPress says:

Themes must have a stylesheet and a template.

This sentence, people must imagine that after the word "a stylesheet", there are some required file not tag.

[mayukojpn]

Screenshot and my notes.

[mayukojpn]

With first patch I'd like to change to it.

Themes must have a stylesheet and a template tag within it.

Or this with second one (I'm not native English speaker, I'm sorry! :p)

Themes must have a stylesheet and a template tag inside it.

[swissspidy]

Perhaps a link to the documentation could be added?

[mayukojpn]

Replying to swissspidy:

Perhaps a link to the documentation could be added?

documentation about requirement files of child theme:
​https://codex.wordpress.org/Child_Themes#How_to_Create_a_Child_Theme

Let me know if I misunderstood your question or wrote wrong link. Thank you so much!

[swissspidy]

Looking at the WP_Theme source code, a theme is broken when there's at least 1 WP_Error. Some possible errors:

• Theme directory does not exist (theme_not_found)
• Themes directory does not exist (theme_root_missing)
• Stylesheet is missing (theme_no_stylesheet)
• Stylesheet is not readable (theme_stylesheet_not_readable)
• Template is missing (theme_no_index)
• Parent theme is missing (theme_no_parent)
• X is not a valid parent theme (theme_parent_invalid)

The The following themes are installed but incomplete. Themes must have a stylesheet and a template. message is just a general warning, while the detailed description is shown below. It is misleading, because a theme can also have errors when it definitely has a stylesheet and a template.

In your case, the child theme was missing its index.php file and I wonder why adding it didn't solve the issue (cache?).

So, my suggestions:

• Change the Template is missing message to something like Main Index Template is missing to make it more clear/helpful. That terminology is already used in $wp_file_descriptions.
• Change The following themes are installed but incomplete. Themes must have a stylesheet and a template. to just The following themes are installed but incomplete.

Any objections?

[mayukojpn]

Replying to swissspidy:

Thank you for reviewing!

I'm sorry, I wrote wrong.
Now I realize that it will work if there are index.php without template tag in style.css. Because WordPress will understand the theme as not a child theme!

My point was the original message was not friendly for people who is building a child theme. Actually child theme can work without any PHP file inside it (And I always do that).

​Codex says:

index.php
The main template. If your Theme provides its own templates, index.php must be present.

theme_no_index error checks if there are index.php OR template tag in a style.css header.

<?php
if ( ! $this->template && ! ( $this->template = $this->headers['Template'] ) ) {
        $this->template = $this->stylesheet;
        if ( ! file_exists( $this->theme_root . '/' . $this->stylesheet . '/index.php' ) ) {
                $this->errors = new WP_Error( 'theme_no_index', __( 'Template is missing.' ) );
                $this->cache_add( 'theme', array( 'headers' => $this->headers, 'errors' => $this->errors, 'stylesheet' => $this->stylesheet, 'template' => $this->template ) );
                return;
        }
}

My request looks getting harder... but it could be Template file or tag is missing or like that? Is it too much for this small column? I understood we couldn't separate message for independent theme and child theme. :(

[swissspidy]

Hmm if the parent theme is missing it should throw a theme_no_parent error though...

[mayukojpn]

Yes, you are right. If there are no parent theme, theme_no_parent error should be shown.

These are combination of actual state and result:

prefer to improove	Theme is	is parent theme installed?	is there template tag in style.css?	Is there index.php file?	result
	Child theme	YES	YES	YES	Child theme will work as child theme.
	Child theme	NO	YES	YES	The parent theme is missing.
YES	Child theme	YES	NO	YES	Child theme will work as parent theme and no error. I agree with you if the parent theme is missing it should throw a theme_no_parent error
	Child theme	YES	YES	NO	Child theme will work as child theme.
	Child theme	NO	YES	NO	The parent theme is missing.
YES	Child theme	YES	NO	NO	Template is missing. I prefer template tag is missing.
	Child theme	NO	NO	NO	Template is missing.

[ericlewis]

This is a stumbling point for new developers, great idea to offer better feedback here :)

Replying to swissspidy:

• Change the Template is missing message to something like Main Index Template is missing to make it more clear/helpful. That terminology is already used in $wp_file_descriptions.

If a theme doesn't have an index.php file, and the style.css headers don't include a Template: header, then the problem is ambiguous. Are you trying to create a stand-alone theme and forgot an index.php file? Or are you trying to create a child theme and forgot to include the Template header?

I think we can expand on ​the error message here, explaining the problem in greater detail. Collating both of your thoughts, here's an idea for error text:

"If the theme is intended to be a standalone theme, it should have a index.php template file. If it's intended to be a child theme, the stylesheet (style.css) should have a Template header (link to proper docs)."

• Change The following themes are installed but incomplete. Themes must have a stylesheet and a template. to just The following themes are installed but incomplete.

Sounds great! The specific details are output in the table so this seems superfluous.

[swissspidy]

35286.diff​ is a patch incorporating the feedback from @ericlewis and myself. See 35286.png​ for how it looks like.

[ericlewis]

Looks great!

[mayukojpn]

That's very good! Thank you very much!

[swissspidy]

Added translator comments

[swissspidy]

In 36638:

Themes: Improve error messages for broken themes.

Props mayukojpn for initial patch.
Fixes #35286.