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

Themes Team Meeting Agenda for August 10, 2021

Channel: #themereview | Time: Tuesday, August 10 2021, 15:00 UTC

The themes team conducts a meeting on the second and fourth Tuesday of the month.
The meeting takes place in the #themereview channel on the WordPress SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. and you need an account to participate.

Along with the fixed agendas, we have an open floor at the end where you can ask or share anything related to themes.

We encourage all members and anyone interested to attend.

Meeting agenda

  1. Weekly updates
  2. Requirements change
  3. Open floor

Weekly Updates

Current statistics can be found on: https://themes.trac.wordpress.org/ 

Themes TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. ticket graph: https://themes.trac.wordpress.org/ticketgraph

Check regular weekly updates here.

Also check,


Requirement changes

The theme requirements page has been updated. You can see it here. Now, all the reviews will be done based on these guidelines.

Thank you all who helped directly or indirectly to make it happen.


Open floor

We will discuss everything related to themes. Attendees can ask or share themes-related things.

Please comment in the comment box below if you have anything to bring up during the open floor.

#guidelines, #meeting, #themes-team

Discussion: Requirements for full site editing themes

As explorations of the minimum viable full site editing theme continues and the outreach program is starting, it is time to have a first discussion about requirements for FSEFSE Short for Full Site Editing, a project for the Gutenberg plugin and the editor where a full page layout is created using only blocks. themes in the theme directory.

Having basic requirements is one of the steps needed for us to be able to open up theme submissions:

  1. Requirements
  2. Update the Theme Check 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 to allow full site editing themes
  3. Strengthen reviewer knowledge
  4. Activate GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ on the theme previewer -Completed

These are discussions points and not a complete proposal.

You can compare the items below with the current requirements.

New code requirements:

Valid 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. markup: There must be no block validation errors on theme switch.

For this requirement, we need to research if it is possible to validate the block markup automatically.

Minimum required files:

  • style.css
  • readme.txt
  • functions.php
  • index.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. (placed inside the block-templates folder)
  • Temporary: Comments.php is required as without it, a PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/preface.php. warning is shown.
  • Theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. (or experimental-theme.json).

Requirements that may need to be adjusted:

Plugins: Themes are allowed to require Gutenberg as long as Gutenberg is needed to enable full site editing.

Options and Settings
Theme options may only be included as:

  • Theme_support
  • Global style settings
  • Block patterns
  • Block variations
  • Block styles

Items under this requirement that become irrelevant or confusing because blocks are used instead of PHP functions:

  • Use 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. for implementing theme options
  • Save options in a single array
  • Don’t use transients for things they shouldn’t be used for, like storing theme options
  • Use sane defaults and don’t write default setting values to the database

Presentation vs Functionality: Images that are not plain placeholder images and essential for the design are allowed.

Items under this requirement that become irrelevant or confusing because blocks are used instead of PHP functions:

  • The theme options should not be pseudo custom post types and save non-trivial user data
  • Non-design related functionality is not allowed

CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Functionality and Features

Items under this requirement that become irrelevant or confusing because blocks are used instead of PHP functions:

If incorporated, features must support the WordPress functionality:  

  • Sidebars
  • Navigation Menus
  • Post Thumbnails
  • Custom Headers
  • Custom Backgrounds
  • Editor Style
  • Logo

Use template tags properly

Include comments.php (via comments_template())

Requirements that remain the same:

  • Licensing
  • AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) (temporary exception for skip to content link)
  • Readme file
  • Importing or downloading
  • Documentation
  • Naming
  • Screenshot
  • Image guidelines (exception for placeholder images that are essential for the design)
  • Stylesheets and Scripts
  • Privacy
  • Selling, credits, and links
  • Child themes

Requirements that it is not currently possible to follow:

Language / translation ready


Request for feedback

  • Which of the current requirements are relevant for full site editing themes?
  • What new full site editing specific requirements needs to be added?
  • How do we best present the requirements for full site editing themes?
    • On a separate page
    • In a separate section of the current requirements page
    • Other, describe your suggestion in the comment

#full-site-editing, #guidelines, #themes

New Project: Rewriting the requirements

Project description

Purpose

Making the requirements clear, easy to follow and easy to check.

Prerequisites

This project will not be starting with a blank slate, but make the best of what we have.

Tasks

In no particular order:

  • Review whether current requirements and recommendations are valid
  • Add new requirements when necessary
  • Reorganize requirements and topics
  • Rewrite requirements to make them easier to understand

 

Project format, mandate, timeline and meeting times

Suggested format

A smaller project group with a separate meeting time is preferred, that way the Theme Review Team can still hold the regular meetings on Tuesdays to discuss other topics.

Mandate

The group should have a mandate to change the wording of the requirements and examples with some exceptions:

Project leads/key reviewers should have access to making changes to the actual documents.

Major changes like completely removing a requirement should still be brought up during a Theme Review meeting.

Suggested meeting times

Every other Thursday at 19:00 CET,  alternating with the automation project meeting.

The Theme Review shindigs on the first Saturday of each month could also be used for longer meetings.

Timeline

The project would need to decide on partial goals, for example monthly or bi monthly milestones to ensure that the project moves forward.

Suggestions:

  • March 4 shindig: Requirements that have been voted on but not added,  should be added to the current requirements page.
  • In june, all requirements that are checked by the new Theme Check 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 should be separated from the rest of the requirements.

 


Our first meeting will be on Thursday, February 23 at 19:00 CET.

Agenda

  • Introduction
    • Let’s see who are interested in helping out.
  • How can we work on the requirements together?
    • How do we record and share our work in progress? Do we need any external tools?
    • Decide who our target audience is to be able to set a “tone” of our content and level of difficulty for the examples.
    • In what format do we present the requirements, keeping time limits and milestones in mind?
  • Decide priorities for march-april
    • Missing requirements (band-aids)
    • Reordering and regrouping current requirements

March 4 Shindig

Requirements that have been voted on but not added should be added to the current requirements page.


Our second meeting will be on Thursday, March 9 at 19:00 CET.

Agenda

  • Continue discussing any previous topics that were not finished during the last meeting.
  • Reordering and regrouping requirements
    • Is the requirement under the correct topic or does it need to be moved or placed under a new topic? We also have topics with only a few requirements that perhaps could be combined into one, like Naming and Screenshot.
    • Are there recommendations that should be moved to the required list? For example the Theme and Author URI.

#guidelines

Using Sane Defaults in Themes

With the release of WordPress 3.9, one of the changes to the Theme Review Guidelines is that Themes must use sane defaults. That means that Themes must not write default setting values to the database. For many Themes, this may seem like a major change; but it doesn’t have to be. This post will step through a few ways to implement sane defaults.

Portability/DRY

To make this method easier, put all of your defaults inside a function:

function themeslug_get_option_defaults() {
	$defaults = array(
		'option_1' => 'value_1',
		'option_2' => 'value_2',
		'option_3' => 'value_3'
	);
	return apply_filters( 'themeslug_option_defaults', $defaults );
}

(Note: by making the return valuable filterable, the Theme defaults can be easily overridden by a Child ThemeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. https://developer.wordpress.org/themes/advanced-topics/child-themes/. or 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.)

We’ll make use of this function later.

Options 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.

Most Themes use the Options API, and will use get_option() to put Theme settings into a global:

$themeslug_options = get_option( 'theme_themeslug_options' );

Knowing that this get_option() caall will return FALSE if the option has not yet been saved to the database, Theme developers have taken to saving default values to the database as part of Theme initialization, like so:

if ( false == get_option( 'theme_themeslug_options' ) ) {
	update_option( 'theme_themeslug_options', themeslug_get_option_defaults() );
}
$themeslug_options = get_option( 'theme_themeslug_options' );

But this is entirely unnecessary. And everything needed to implement a better solution already exists.

As a first step, consider that get_option() includes a second parameter, which specifies the default value to return, if nothing is returned from the database:

get_option( $name, $default );

So, the simplest solution is merely to tell get_option() to return the defaults, using the function we previously defined:

$themeslug_options = get_option( 'theme_themeslug_options', themeslug_get_option_defaults() );

This works, but isn’t perfect. It will return the Theme-defined defaults if the user hasn’t saved settings to the databse. But if later versions of the Theme add, remove, or change options, this might break, since the return value is either/or: either the database-saved setting, or else the defaults. So, if the user saves settings, and then a new setting is added in a later Theme version, the new setting value won’t be included in $themeslug_options unless/until the user saves settings again.

The solution is to merge the arrays, rather than to return one or the other. WordPress has a coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. function specifically for this purpose: wp_parse_args(), which will use the settings array, and “fill in the blanks” with the defaults array:

wp_parse_args( $settings, $defaults );

Caveat: bearing in mind that wp_parse_args() expects both parameters to be arrays, and knowing that get_option() returns FALSE by default, be sure to specify get_option() returns an empty array by default: get_option( ‘theme_themeslug_options’, array() ); otherwise, wp_parse_args() will (might – see note below) choke if the user hasn’t saved settings to the database.

The construct will look something like this:

$themeslug_options = wp_parse_args( 
    get_option( 'theme_themeslug_options', array() ), 
    themeslug_get_option_defaults() 
);

This is perhaps the simplest, most elegant way to implement sane defaults.

(Note: according to Otto, passing an empty arrayy() as the second parameter to get_option() isn’t necessary. In his words: “The wp_parse_args() function checks for the first parameter to be an object or an array. If it’s neither, then it calls wp_parse_str on it, because it can take a GET URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org-like array of parameters too. The wp_parse_str() function calls PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/preface.php.’s parse_str on it, and does a deep strip_slashes if magic quotes is on, then filters the result. So, because false maps to the empty string, parse_str will return an empty array for it, so passing false to wp_parse_args should be A-OK and probably has been like that for a very long time. Doesn’t hurt to add the empty array(), but doesn’t really change anything.” YMMV.)

Theme Modification API

Using the Theme Modification API (get_theme_mod()/get_theme_mods()) is fairly similar.

An individual setting can be called via:

get_theme_mod( $name, $default );

But perhaps more useful, all settings can be called via:

$themeslug_options = get_theme_mods();

Since get_theme_mods() returns an array, you can use the same technique as with Options API settings:

$themeslug_options = wp_parse_args( 
    get_theme_mods(), 
    themeslug_get_option_defaults() 
);

Portability/DRY (Part 2)

To be able to use this method throughout the Theme, wrap the wp_parse_args() call inside a function:

function themeslug_get_options() {
    // Options API
    return wp_parse_args( 
        get_option( 'theme_themeslug_options', array() ), 
        themeslug_get_option_defaults() 
    );
    // Theme Mods API:
    /*
    return wp_parse_args( 
        get_theme_mods(), 
        themeslug_get_option_defaults() 
    );
    */
}

Then, wherever you need access to Theme options:

$themeslug_options = themeslug_get_options();

From there, you can globalize $themeslug_options, or cache/transient it, etc. When you need to add a new option, simply add the new option default to the defaults array, and the Theme will handle it automatically.

#guidelines, #sane-defaults, #settings-api, #theme-mods-api