Proposal: allow themes to add a top-level admin-menu

The Themes Team would like to add the following requirements and we would also like to hear your opinions on this matter.

Themes should add a page under the Appearance menu using add_theme_page. If they need to have sub-pages (like for example documentation, FAQs, donation link etc), then they are allowed to use add_menu_page and add_submenu_page, provided they follow these requirements:
 * You are allowed to create only one (1) main page using `add_menu_page`. The recommended maximum number of sub-menu pages (`add_submenu_page`) is three (3).
 * The `$position` (priority) parameter must be `null` or only occupy the spot above the Appearance page (59). Check the code example on how to set the correct priority.
 * `add_submenu_page` must be used only on the page created using `add_menu_page`.
 * If you recommend plugins via TGMPA, you are required to use the `parent_slug` configuration option (this should be the top-level page's slug).
 * Core UI patterns must be used. You are not allowed to style the menu & submenu page links in any way. The admin color scheme must remain the same.
 * Use only monochromatic icons. It must account for the admin color scheme.
 * The title must be kept short and not include spam.
 * Child themes are allowed to add one extra sub-page or remove the parent's pages and add its own.

Before you start mentioning that this will be abused and it’s an open door for spam, please consider these:

  • You can only have one theme active, which means there can only be one top-level link and it will not occupy that much screen real estate.
  • Themes are not allowed to add a panel with information to the block editor sidebar/tools panel. Besides, the Customizer will be used less and less and theme authors need to have a visible way to list their theme’s documentation & information.

If you need more info, please check add_menu_page and add_submenu_page.

Added 15th July by @williampatton

For additional context about this idea we had a conversation in slack about this that started from this message and continued for quite some time – partially async.

http://wayback.fauppsala.se:80/wayback/20201029183240/https://wordpress.slack.com/archives/C02RP4Y3K/p1594225597110800 (slack account required)

Added July 18th by @acosmin

After a few discussions and taking @greenshady ‘s ideas into consideration, we’ve decided to:

  • remove the sub-pages limit, we recommend using a maximum of three (3)
  • the menu page priority can either be null or only occupy the position above the Appearance page. That’s 60 – 1, 59. This will also help users know where to look for this page. You can use this code to make sure your page will always be after Appearance:
function prefix_admin_menu() {
	$menus = $GLOBALS[ 'menu' ];
	$priority = array_filter( $menus, function( $item ) { 
		return 'themes.php' === $item[2];
	} );
	$priority = ! empty( $priority ) && 1 === count( $priority ) ? key( $priority ) - 1 : null;

	add_menu_page(
		__( 'Theme Name Title', 'textdomain' ),
		__( 'Theme Name', 'textdomain' ),

		'edit_theme_options',
		'theme-options.php',
		'',
		'dashicons-admin-customizer',
		$priority
	);
}
add_action( 'admin_menu', 'prefix_admin_menu' );

If you have suggestions on how to improve this code snippet, please do it in the comments.

Theme related stuff belongs under the Appearance menu. That is what the top level menu is for really. Nothing has changed since the past decision was made to not allow top level theme pages.

Now the Theme Page currently resides under the Appearance menu and I don’t really understand how a decline in Customizer use will prevent visibility of theme stuff. The customizer is just an Options API and Theme pages will still be under Appearance. Is the Appearance core menu going away?

It’s about better exposure for up sell in the end, which I find surprising is not mentioned in the above post.

I believe that any user that wants to read documentation or Upgrade to Pro knows where to go…..if not Customizer which will be here for a while….then the Theme Page. The main reason for this request is to provide more exposure for up sell which will just lead to more spam…..which I am against.

Now if theme documentation is the main purpose of this then I would I would have no problem with a top level page if limited to one page and only a simple “Upgrade to Pro” at the top of the page. Authors can then up sell their theme on their own site. A simple “Upgrade to Pro” link also is simpler to moderate…while “no obtrusive up sell” is purely subjective. We all know the squeaky wheel rule where authors seem to think the bigger and bolder the up sell, the better chance of an up grade.

So if documentation is really the primary concern, let’s limit the up sell to a simple “Upgrade to Pro” link which would let the users easily connect to the Author Theme Up Sell page for more details, and at the same time ensure the top level Theme Page remains spam free.

Do we have to repeat here all our arguments already made in Slack? Or are you going to judge this by the comments received here alone?
I have no idea how decisions are made these days.

Since the Theme Repository is not a marketplace, and we don’t want our policies to imply that it is, then any argument about usage patterns in the admin is moot. The admin is also not a marketplace.

Since there is only one active theme, it is an anti-pattern to have anything theme related outside of the Appearance menu. Users have been trained for years to expect that theme stuff belongs there. It would be a detriment to the users and their habits to put it anywhere else. We also have a rule (perhaps it isn’t written down) that the theme should not affect the admin, but only the theme page in the admin. I think changing the admin menu is affecting the admin, which themes shouldn’t be doing.

Given that there have been years of experience to arrive at the current rule, that should not be thrown away in an instant. There are good reasons why it exists in the first place.

i think you should also mention that child themes are not allowed to do above. only parent themes are allow to add one parent menu and sub menus.

Does that mean Child Themes creators aren’t allowed to add some documentation/donation link? That looks quite unfair.

Updated the requirement with these 2 points:

  • If you recommend plugins via TGMPA, you are required to use the `parent_slug` configuration option (this should be the top-level page’s slug). Also, this counts to your sub-pages limit.
  • Child themes are allowed to add one extra sub-page or remove the parent’s pages and add its own.

It would help to, at minimum, link to the previous discussions so that those new to this conversation get the full context.

Good callout, I added a link to where conversation started. Thanks for suggesting this 🙂

I’m not a theme developer, but I’m a little surprise about this topic… I guess what you ask is only to be able to do it “legally”… because I’ve seen many themes that do add one, if not two, top-level menus…
Personnally, as a user, I have nothing against it… Most if not all the themes I use now are basic and therefore the Appearance menu is enough, but for some bigger themes (Asana, Jupiter, etc.) I don’t see it as negative to have their own menu… After all, IF the rules are well followed, it’s just one more menu… A lot of plugins do that and we don’t argue “all plugins settings should be under plugins”… And if there is something that can become messy, it’s way more plugins than themes…

In most cases, companion plugins move the theme’s menu item to the 1st level anyway 🙂

Updated the post with some changes.

The team has often complained that there are too many requirements, yet here you are swapping one requirement for 8. It seems like a regression to me.