Discussion: How to handle custom settings screens in block themes

In 2015, the Themes Team implemented a guideline that required all theme settings pages to use the Customize APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. This was after the API had been in WordPress and stable for nearly three years.

There were two primary reasons for this:

  • It meant that users could expect a standard options interface from any theme in the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ theme directory.
  • It simplified the review process because all the code was built on top of the exact same API. This made it easier to check for security issues, in particular, and shorten the time it took to review a theme.

Over the years, this guideline was generally accepted as the best path forward by members of the Themes Team.

In large part, the decision single-handedly cut out the vast majority of insecure settings pages that were being implemented in themes (mostly from a couple of copy-paste scripts that were popular around the web). That was a big win for theme authors, reviewers, and users. The importance of this change is not to be taken lightly and is very much at the forefront of any discussion around theme settings.

Fast forward to today—now eight years later. The Themes Team is at another pivotal moment that could partially shape what the theming landscape looks like for years to come.

A new era: blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. themes and custom settings screens

When the customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. guideline was introduced, it was during the classic theming era. There was no concept of block themes at the time. While it is possible for a block theme to use the Customize API today, it is no longer part of the expected user experience for users who have activated a block theme.

In fact, there’s no real expectation that a block theme will have any settings screen at all outside of what’s possible via Appearance > Editor in the admin.

Now that the block theming system and the Site Editor are about seven months out of betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process., it means that theme authors will continue building more and more block themes. And with that, the Themes Team should expect to see more experimentation around this new paradigm. There really is no guidebook on what to expect as theme authors try to solve both old and new problems in a world that is heavily based on the block system and modern JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/..

In particular, the expectation is that theme authors will begin trying new things with ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/.-based JavaScript components that are bundled with WordPress. Not only are interfaces changing, but the underlying programming language now involves much more JavaScript.

The discussion: feedback wanted

In the October 10, 2023 meeting, the Themes Team began the discussion on what to do about the settings page requirement going forward. The decision from that meeting was to open the discussion up for feedback from the wider community.

The Customize API requirement is well established for classic themes, so this discussion is solely focused on block themes.

The questions:

  • Should the team loosen the requirement on the current settings page requirement for block themes, allowing experimentation with React components?
  • If so, what guardrails—if any—should be put in place on what themes can do?

It’s also important to frame this conversation within the overall guidelines and not get into the weeds of unrelated topics. For example, settings would still need to fall within “theme territory” (i.e., they should be related to design). The decision that needs to be made is focused solely on the settings page guideline:

Use the Customizer for implementing theme options.

The other thing to be aware of is that any decision to loosen that specific guideline can impact active reviewers. That means making sure that they are up to date on modern WordPress JavaScript coding standards and can handle an upward trend of more themes with heavier JavaScript code bases. Otherwise, the progress over the last few years to have a faster review queue could also be lost. With that in mind, it’s important for any active reviewer to voice any concerns about any potential changes.

Now the floor is yours. How would you handle the settings page guideline for block themes going forward?

Props to @kafleg and @ndiego for feedback and review on this post.

#discussion-topic, #guidelines

What’s In a Name?

To paraphrase a famous line from Shakespeare’s Romeo and Juliet, “a theme by any other name would look as sweet” … and in the same manner that one can see “code is poetry”, a good theme will be known by its quality more so than by its name. The name should just be a point of reference so you can find it more easily.

Also keep in mind, that when you choose a theme name you should recognize what and how that name should be used within the theme’s code. For example, the theme name will directly translate into the theme’s slug. The theme slug should be expressly used as the theme’s textdomain. Also keep in mind, in many cases the theme name/slug should also be used as the prefix for any of the theme’s functions that may be used to ensure there is minimal chance of code clashes and/or conflicts.

So what makes a good name? I would say something unique but still easy to remember. People might joke about naming a theme “Fred” which is all fine especially if Fred is a great theme then it will be rather easy to search for, but seriously … Fred?!

Why not try something a little more interesting, something to make the theme stand out a bit. Maybe “Black Gypsy Moth” … or “Hecuba’s Huzzah” … how about “SKU Biddy Bah Boo”?! These can all be good, or bad, theme names but for the most part the real test will be in the code and design; and, what the theme does for the person using it.

Also, don’t forget the power of a single word theme name, and that does not mean to say it has to be a “real” word. Why not try making something up yourself … could you see “Gooderama”, “Crazylicious”, or even “Bestest” as a theme name? I can. I might even grab one of these for myself. It’s still first come first served so be quick about it, these are all free to use.

Will playing off of another popular name, or flavor of the day/week/month really be that valuable down the road? Maybe, but why not stand out with a truly unique name upfront rather than share the limelight with something or someone else.

Part of the fun and the challenge of theme design is giving the finished product a name that suits the work. Although this is something that often needs to be done before the code is written, it is still worth the time to take a step back and think of something unique to aspire to … you’re not just creating a copy of another theme you are creating your own unique work, doesn’t it deserve a unique identifying name as well?

#discussion-topic, #theme-names

Improving our theme previews

As many of you may, or may not, have noticed there are currently over two thousand themes available in the repository. I think that is amazing. Seriously, huge thanks to all those that have contributed not only their time but their efforts as well.

One thing I noticed some time ago was the mentioning of the theme previews. I can’t recall where it was brought up but I do recall it mentioned that it wasn’t the greatest preview of a theme, or themes really. I do hate to admit it but it is fairly true. The current preview is lacking on some things.

One of the things being post formats. Currently the theme preview is just a few posts and a few pages. I think we can do a little better now. I’ve brought up a ticket a few times: #30 in the Meta trac.

Here are some of the things I think we can not only improve upon but can contribute to.

  • Sample data
  • Images
  • Video
  • Audio


Simple and to the point. We need posts and plenty of them. How about quick little tidbits like how to set up a front page, or changing the image headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes.. Doesn’t have to be huge.


Galleries. Sliders. Single images. We need more boats!! Okay not really but if you have them it would be awesome.


I think we can find a way to contribute a few videos here and there. I know there are some themes that have video format support and I would love to be able to accent that in some way.


I’m thinking podcasters and maybe musicians.

So there you have it. Let’s discuss!

#community, #discussion, #discussion-topic, #wporg

Theme Review Points of Emphasis

Here are some of the things I’ve been looking for specifically when performing the final audit of approved Themes waiting to be made live. These are the most-frequent issues when reopening a ticket for an approved Theme. Please consider these as “points of emphasis”, to help improve the consistency of our reviews.

Prerequisites – these should be verified before even looking at Theme code

  • ThemeURI/AuthorURI: the first thing I do is check ThemeURI/AuthorURI for appropriateness.
  • If ThemeURI is a commercial Theme shop, or if the Theme is Up-Sell, I verify the commercial-Theme license, to ensure that it is 100% GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples./compatible
  • Credit Link: I then verify that the Theme has only one credit link, in the footer, that the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org is either ThemeURI or AuthorURI, and that link text and attributes are not SEO-seeded
  • Licensing: next, I check everything bundled with the Theme, verify that copyright/license attribution has been included, and that all licenses are GPL-compatible – fonts, images, jquery scripts, iconsets, everything. If it’s bundled with the Theme, it either needs to be copyrighted as part of the Theme, or include copyright attribution and be distributed under a GPL-compatible license

Code Quality

  • header.php: verify that HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. <title> tag includes only the call to wp_title(). Any additional content, if required, must be added via wp_title filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output..
  • header.php: verify that no scripts or stylesheets are hard-coded in the document head (except for the main stylesheet, and IE-conditional stylesheets)
  • header.php (usually): verify that calls to wp_nav_menu() include the ‘theme_location’ parameter, and do NOT include the ‘menu’ parameter
  • functions.php: verify that all function calls are placed inside of callbacks, hooked into explicit actions. No functions should execute directly from functions.php.
  • functions.php: verify that the Theme doesn’t call PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party-territory remove_action() calls, such as removing the WordPress version generator from wp_head
  • functions.php: verify that Theme does not add function_exists() conditional wrappers for coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. functions introduced more than two prior major WordPress versions (currently: for any core function introduced prior to WordPress 3.5)
  • Template files and custom page templates: verify that Theme uses new WP_Query for secondary loops, and pre_get_posts to modify the main query, rather than query_posts()
  • Theme Options: verify that Theme options are being stored as a single array, are being sanitized on input, and escaped on output
  • Theme Options: verify that Theme options do not include “Plugin territory” options such as analytics/tracking code

Addressing these issues would cover about 99% of tickets currently being reopened after approval.

#discussion-topic, #guidelines

Discussion: Theme Internationalization

How should Themes handle Internationalization?

Currently, Internationalization is recommended, and if internationalization is incorporated, Themes are required to use theme-slug as a unique textdomain.

What else should be considered? For example:

  1. If Themes include translation, should all strings be required to be translatable?
  2. If Themes do not include translation, should any strings be translatable?
  3. What else should be considered?

In other words: what constitutes best-practice, and what should be avoided, when implementing Theme internationalization?

#discussion-topic, #guidelines, #internationalization