WordPress.org

Make WordPress Core

Opened 23 months ago

Closed 21 months ago

Last modified 21 months ago

#35286 closed enhancement (fixed)

Broken theme error message is very confusing

Reported by: mayukojpn Owned by: swissspidy
Milestone: 4.5 Priority: normal
Severity: normal Version:
Component: Themes Keywords: ux-feedback has-screenshots has-patch commit
Focuses: administration Cc:

Description

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.

Attachments (6)

screenshot_2016_01_02_20_15.png (38.1 KB) - added by mayukojpn 23 months ago.
Screenshot and my notes.
child-theme_broken_message.diff (583 bytes) - added by mayukojpn 23 months ago.
child-theme_broken_message_inside-it.diff (581 bytes) - added by mayukojpn 23 months ago.
35286.diff (2.2 KB) - added by swissspidy 21 months ago.
35286.png (59.1 KB) - added by swissspidy 21 months ago.
35286.2.diff (2.3 KB) - added by swissspidy 21 months ago.
Added translator comments

Download all attachments as: .zip

Change History (22)

@mayukojpn
23 months ago

Screenshot and my notes.

#1 @mayukojpn
23 months ago

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.

Last edited 23 months ago by mayukojpn (previous) (diff)

#2 follow-up: @swissspidy
23 months ago

  • Focuses ui accessibility template removed
  • Keywords ux-feedback added
  • Summary changed from Child theme error message is very confused. to Broken theme error message is very confusing

Perhaps a link to the documentation could be added?

#3 in reply to: ↑ 2 @mayukojpn
23 months ago

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!

#4 @mayukojpn
23 months ago

  • Keywords has-patch added

#5 follow-ups: @swissspidy
23 months ago

  • Keywords needs-patch added; has-patch removed
  • Milestone changed from Awaiting Review to Future Release

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?

#6 in reply to: ↑ 5 @mayukojpn
23 months ago

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. :(

#7 @swissspidy
23 months ago

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

#8 @mayukojpn
23 months ago

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.
Last edited 23 months ago by mayukojpn (previous) (diff)

#9 in reply to: ↑ 5 @ericlewis
23 months ago

  • Milestone changed from Future Release to 4.5

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.

This ticket was mentioned in Slack in #core by swissspidy. View the logs.


23 months ago

@swissspidy
21 months ago

@swissspidy
21 months ago

#11 @swissspidy
21 months ago

  • Keywords has-screenshots has-patch added; needs-patch removed

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

#12 @ericlewis
21 months ago

Looks great!

#13 @swissspidy
21 months ago

  • Keywords commit added

#14 @mayukojpn
21 months ago

That's very good! Thank you very much!

Last edited 21 months ago by mayukojpn (previous) (diff)

@swissspidy
21 months ago

Added translator comments

#15 @swissspidy
21 months ago

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

In 36638:

Themes: Improve error messages for broken themes.

Props mayukojpn for initial patch.
Fixes #35286.

#16 @johnbillion
21 months ago

  • Version trunk deleted
Note: See TracTickets for help on using tickets.