Author Archives: Justin Tadlock

Justin Tadlock 3:20 pm on January 11, 2024
Tags:   

New Block-Focused Theme Handbook Docs and What’s Coming in 2024

I hope everyone had a good break over the holidays. I know I caught up on some much-needed rest and am now excited to get back into the swing of doing fun things with WordPress themes.

Now it’s time to discuss the current progress and next steps of one of our biggest projects of 2024: the Theme Handbook overhaul.

What Is the Theme Handbook Overhaul?

This is a project that the theming community agreed to take on last year. Its goal was to give the Theme Handbook content a refresh, primarily focusing on modern 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. theme development.

You can read the initial proposal and previous project updates here:

The ongoing work is tracked via the Theme Handbook Overhaul tracking ticket on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/.

The Project’s Progress

In 2023, five new/updated chapters were published in the handbook:

The primary focus of these first five chapters is to introduce theme creators to the block theming system. Most of this documentation is 100% new. If you haven’t browsed the handbook for a while, now is a great time to catch up!

There are also eight draft articles that have yet to be published.

In terms of “chapter count,” that’s nearly half of the project. But if looking at the actual new content that needed to be created, it’s probably closer to 2/3 of the way toward the finish line.

The Next Steps

The plan is to complete the entire overhaul by the end of Quarter 2 (June 30) of 2024. I believe we can get the bulk of the new content published or drafted in Q1, leaving most of Q2 for final touches and cleanup.

In the coming months, there are still six chapters left to create or update:

  • Patterns (recently added to the outline)
  • Classic Themes
  • Advanced Topics (mostly drafted)
  • 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)
  • Guides
  • Contributing

The Classic Themes, Advanced Topics, and Guides chapters are mostly content updates and a bit of reorganization. These are what I’d call “good first issues” for anyone who wants to contribute but is not ready to write a full documentation article on their own.

The Patterns chapter was recently added to the outline because patterns are a first-class tool in WordPress that will only continue to become more powerful. There is currently a single Block Patterns doc, but it needs to be expanded into multiple articles that showcase each pattern feature. If you like to tinker with patterns, this could be a fun chapter to contribute to.

One area where the project really needs a volunteer is for the Accessibility chapter. It’d be great to have an expert in the field to review and expand upon the existing documentation.

Get Involved

To get involved, all you need to do is:

You can reach out for help with this in the #docs or #themereview 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/. channels. You can also pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me (@greenshady) directly if you have questions.

Props to @kafleg for reviewing this post.

#theme-documentation

Justin Tadlock 1:34 pm on October 17, 2023
Tags: ,   

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

Justin Tadlock 6:46 pm on September 15, 2023
Tags:   

Theme Handbook Overhaul: Phase 3 (Publishing Content)

In April 2023, there was a proposal for overhauling the Theme Handbook, which included an initial outline of what a new handbook might look like. After two public meetings to fine-tune the details of the outline and discuss the project, we moved on to Phase 2. This phase meant writing the new content for the handbook.

Since then, the work has been tracked on GitHub. Now it is time to step into the next phase of this project, but first:

A progress update

The overarching outline for the new handbook is:

  • Welcome to the Theme Handbook
  • Chapter 1: Getting Started
  • Chapter 2: CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Concepts
  • Chapter 3: Global Settings and Styles (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.)
  • Chapter 4: Templates
  • Chapter 5: Features
  • Chapter 6: Classic Themes 
  • Chapter 7: Advanced Topics
  • Chapter 8: 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)
  • Chapter 9: Guides
  • Contributing

Thus far, chapters 1-3 (Getting Started, Core Concepts, and Global Settings and Styles) are near completion. That may not seem like much in comparison to the whole, but these are some of the heaviest chapters, at least in terms of new content that must be written.

Much of the content from the Classic Themes and Guides chapters already exists (plus a few docs from the other chapters). They may simply need to be reorganized based on the outline.

Publishing content in Phase 3

In the coming weeks, we should start bringing new content into the handbook, starting with Chapter 3: Global Settings and Styles. Then, as Chapter 4: Templates, Chapter 5: Features, and beyond are written, publish them when ready.

Why skip over the first two chapters?

The first two of the new chapters, Getting Started and Core Concepts, cannot be moved to the handbook until more of the later chapters are published. The primary reason for this is because they are learning pathways to more advanced topics. This means that they have a lot of links to content that hasn’t been written/published yet.

Later chapters are much more self-contained. This means that they can go live without having to wait for all of the new handbook content to be written first.

So both Phase 2 (Creating Content) and Phase 3 (Publishing Content) will now be running simultaneously.

Any help reviewing the current drafts, particularly under Chapter 3: Global Settings and Styles, would be very helpful as we kick-start this next phase. Check out the tracking ticket for the individual tickets.

Phase 4 and beyond

It’s still a little too early to get into the final phase of this project. But once we move most of the new content along, we will discuss how to proceed with the final migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. to the new handbook and any remaining cleanup.

My hope is that we have a new Theme Handbook by the end of 2023. I’m certain there will be continued work, things that we missed, and new features on the horizon. The handbook should be a living document, forever evolving alongside WordPress. This project is as much about setting a foundation for the future as it is revamping the current handbook.

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

#theme-documentation

Justin Tadlock 2:34 pm on May 17, 2023
Tags:   

Theme Handbook Overhaul: Phase 2 (Creating Content)

On April 4, there was a proposal to overhaul the WordPress Theme Handbook that would bring the documentation more up to date, create a new structure, and be more inviting to first-time theme creators.  Since then, the Themes Team has held two meetings where the proposal could be discussed:

  • April 11 team meeting (notes)
  • April 18 handbook meeting

The meetings and open discussion on the proposal post provided an opportunity for everyone to discuss the initial outline (Google Docs link) for the new handbook. Based on feedback over the past month, this outline has largely stayed the same with a handful of adjustments. Thank you to everyone who participated in these discussions and helped shape it into what it is today.

The next steps

Now that we have solidified the overall new handbook outline, it is time to start moving forward with the next steps. The following lays out a plan to tackle actually reshaping the handbook into something new.

This is the part where the project could really use your help! The more people involved with creating content, the more successful this endeavor will be.

Source of truth: GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ ticket

The Theme Handbook Overhaul Tracking Ticket will serve as the primary location to track and manage the overall progress of this project. 

Essentially, this ticket will list all of the chapters, pages, and sections that need to be created or updated. 

Creating tickets

See something you want to work on? Create a new ticket in the Documentation Issue Tracker (be sure to read the Contributing Guidelines). Once a ticket has been created, we can add it to the primary tracking ticket. 

Creating content

The current plan is to build the new handbook within the existing handbook, moving and adjusting things as necessary. Once most or all of the work is done, the old menu will be replaced with a menu that reflects the updated structure.

As you create content for a specific issue, it will eventually need to be added manually to the Theme Handbook. Because this is an entire overhaul of the handbook, some new pages may need to wait for other pages to be written before they go live. Decisions on how best to handle this may happen on a case-by-case basis.

Reshaping the outline

While we have a pretty solid outline at the moment, things tend to change when you actually get into creating the content of the project. Sometimes things need to be rearranged, added, or changed in some other way. That is not an issue at all, and we can address those situations as they arise.

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)

The new handbook structure proposes a larger Accessibility chapter. Any contributors who are well-versed in a11yAccessibility 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) are definitely needed for this project’s success.

When will the project be complete?

A realistic goal is likely the end of Quarter 3 of 2023. This can be adjusted as needed, but it helps to have a deadline to shoot for. 

With that said, the handbook will never truly be “complete.” Documentation is a living, breathing creature that needs continual care. Even when the initial overhaul is finished, there will always be the need for contributors to continue making it better.

Get involved

If you would like to contribute, just head over to the tracking ticket and find a sub-ticket that needs to be worked on or create a ticket for a handbook page that has yet to be created.

Props to @poena and @kafleg for review.

#theme-documentation

Justin Tadlock 2:46 pm on April 4, 2023
Tags:   

Theme Handbook Overhaul Proposal

The WordPress Theme Handbook has a lot of great content from numerous contributors over the years. It is filled with wisdom and experience learned from their trial, error, and work. For everyone who has volunteered their time to build this resource: thank you.

The problem with handbooks for ever-changing software is that they need a large re-tuning from time to time. The Theme Handbook has reached that point in its lifespan.

It was created during a time when classic themes were the only method of front-end design for WordPress. Much of its content now exists in a transitory state between classic and modern 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. theming. This has created a scenario where the handbook sometimes reads more like patchwork than if it were built with a single vision. That is often a natural result of adding new documentation over years.

The following is a proposal to give the Theme Handbook the refresh that the theming community deserves.

A New Handbook

Over the past several weeks, I have created an initial outline of what the Theme Handbook could look like. This was based on an analysis of the current content in the handbook and Codex and early feedback from the handbook reps. The outline is also forward-looking with the goal of creating a guide for theme creators in the coming years.

Read the outline document →

I want to stress that this outline is a starting point, a way to get some movement on the proposal. It is not set in stone. The goal is for the theming community to reshape it into something that helps everyone, including both first-time creators and seasoned developers. We may end up with something entirely different from the current outline document.

This proposal is to overhaul the entire Theme Handbook. That means that no idea is  too “crazy” during this stage. So, dream big and share your vision for what the handbook should be in the comments below.

With that in mind, it is important to set some dates and not leave this so open-ended that nothing moves forward. Therefore, the feedback period for the outline ends on April 28, 2023. That provides nearly a four-week period for us to work alongside each other to create an outline for a new theme handbook.

The outline proposal will be on the agenda for discussion during the Themes Team meeting on April 11, 2023 at 15:00 UTC. 

There will also be a dedicated meeting on April 18, 2023 at 13:00 UTC via the #themereview channel on 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/.. Everyone is welcome to join and discuss this proposal in detail.

Questions and (Some) Answers

How do I participate in the outlining process?

There are currently four ways to get involved:

  • Leave a comment on this post with your feedback and ideas.
  • Discuss during the Themes Team meeting on April 11, 2023 at 15:00 UTC via the #themereview Slack channel.
  • Join us for the outline proposal meeting on April 18, 2023 at 13:00 UTC via the #themereview Slack channel.
  • Make suggestions directly in the Google Doc for the outline.

What are the next steps after the outlining process?

In the upcoming meeting, we can start to define the next steps on following through with this proposal. This should include, at least, a new ticket on the Documentation Issue Tracker with an overarching plan.

Who will create the content for the handbook?

We all will. The Theme Handbook is and has always been a community project. The more people involved, the better the resource is for us all.

What will happen to existing content?

There is no reason to remove the content the handbook already has. There is a lot of great material there that we should carry forward. Some of it might need to be updated or reorganized, but that can be tackled during the next step. The goal at the moment is to primarily improve the overall outline and flow of the handbook.

Why are Classic Themes in a single chapter?

The goal of the outline was to explore the handbook from a modern perspective and one that will best serve creators in the coming years. It makes sense that the focus of the handbook should be on block theming, especially now that the Site Editor is 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.. Block themes are the present and future of WordPress. 

The outline also makes room for all of the existing content to be migrated to appropriate sections, much of it under a dedicated Classic Themes chapter. Classic theming isn’t disappearing, but the current handbook often makes for confusing reading jumping back and forth between classic and block theme examples.

Like the rest of the outline, this is 100% open for discussion.

What happens to permalinks with the current handbook?

I don’t have an answer for that yet. It would certainly be a part of whatever the final proposal becomes. Some ideas that have been thrown around so far have been a redirect solution or to create a “v2” of the handbook with the old version being archived in much the same way as the Codex still exists. I also don’t think that is a major concern until the outline is finished. It may be easier to simply incorporate new sections/pages into the existing handbook. Whatever the case, it’s best not to let this discussion deter us from creating a new vision.

In other words: let’s cross that bridge when we come to it.

Will there be a new design?

The handbook designs are outside the scope of the Themes and Documentation teams. The Design team has been routinely sharing what many of the pages of an upcoming redesign will look like via the #design-share tag. There is a definite need for a full overhaul of the design that works well for documentation-style pages. Anyone interested in that aspect should visit the Get Involved page of the Design Team handbook.

Props to @poena, @kafleg, and @juanmaguitar for their feedback on this proposal.

#theme-documentation