Introduction to theme.json - Tutorial

[courtneyr-dev]

Workshop is submitted through https://learn.wordpress.org/workshop-presenter-application/

CHECKLIST: Workshop Development Checklist

• Provide feedback of the idea
• Workshop submitted to the team for Q/A review https://blog.wordpress.tv/submission-guidelines/ & https://make.wordpress.org/training/2021/08/17/proposal-brand-guidelines-for-learn-wordpress-content/
• Workshop submitted to WPTV https://wordpress.tv/submit-video/
• Workshop created
• Workshop published on WPTV
• Workshop created on Learn.WordPress.org
• Lesson plan has been published
• Vetted by instructional designers for content idea
• Vetted by deputies for contributor reputation
• Workshop published on Learn.WordPress.org
• Workshop announced to training team
• Workshop announced to creator
• Workshop announced to Marketing Team for promotion
• Workshop post is reviewed for grammar, spelling, etc.
• Workshop is captioned https://learn.wordpress.org/handbook/handbook/workshop-captions-and-transcripts/
• Gather feedback from workshop viewers/participants

[azhiya]

@wparasae are you also working on this?

[wparasae]

Removing myself from this issue temporarily. I'm doing a big push to finish what I've already started as I gear up for the future course; other people may work on this if they desire. Otherwise, I will likely pick this back up as part of the larger "Build a Block Theme - Low Code" course.

[webtechpooja]

It is more relevant to be in the Ready to create column as Sarah is not working on it. SO anyone else if want, they can pick it.

[courtneyr-dev]

outline support was also added to blocks and elements via theme.json. For more information about overall changes to theme.json, please see the Expanded theme.json support and Styles options section below.

Code examples: view examples provided in the Styling elements in block themes dev note

Adoption approach: opt-in.

Key Make Posts/GitHub/Trac Issue(s):

Styling elements in block themes dev note.
YouTube video from Dave Smith going over these new options.

[jonathanbossenger]

As I've spent the last 6 months getting ramped up on block themes and theme.json, I'd like to take a stab at this.

However, theme.json is a BIG topic, there's so much to cover. So I'd suggest we pare this video down to an Introduction to theme.json, covering the following:

• Overview of theme.json, what it is, what it can do
  • JSON object that uses the schema for auto-completion
  • developer can enable theme settings and create setting styles, and then apply styles globally, or to block-level elements
  • replaces a lot of add_theme_support from classic themes
  • can also register custom templates and template parts
• Enabling theme settings
  • setting appearanceTools to true
• Creating theme settings
  • creating a theme-specific text color
• Applying styles
  • globally
  • to elements (since 6.1)
  • to a block

And then include extensive references back to documentation for further reading.

[jonathanbossenger]

Relevant docs/links:

• https://make.wordpress.org/core/2021/06/25/introducing-theme-json-in-wordpress-5-8/
• https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/
• https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/
• https://developer.wordpress.org/themes/advanced-topics/theme-json/
• https://make.wordpress.org/core/2022/10/10/styling-elements-in-block-themes/

[jonathanbossenger]

WIP Tutorial Script

[jonathanbossenger]

theme.json.mp4

Tutorial ready for review

[westnz]

Review:

Excellent work, Jonathan! Great examples were used. I could easily follow all the steps. 🎆

0:14 - 1:30
What about ensuring that the first part of what you are saying is exactly the same as on the screen? When I started reading the slide, and it didn't correlate exactly with what was being said, I got a bit lost. The transition from one point to the next would've worked well if you only read out exactly what was on the screen, but I realise you needed to elaborate. What about adding other screenshots of examples etc, to help see or visualise what you are talking about? Or maybe you could have separate slides for each point, with the first part of what you are saying the same as on screen.

Check the recording at 1:23 :-)

[wparasae]

Your tone is so friendly! I love how clearly you're coming into your voice while making these, Jonathan. You've managed to take one of the most complex topics in WordPress right now and condense it into eleven minutes.

I cannot overstate how impressive that is. Well done!

You've answered questions that lingered in the back of my mind about this, and now I understand how they work in a big way. Do you mind if I add this into the "Create Your First Block Theme" course as a supplemental material? Seriously, this is glorious!

Ellaborating on Wes' suggestions:

1. (Moderate change suggestion) Between :25-1:30, Add a screenshot or two of the styles / some of the settings that can be turned off and on. I'd suggest showing the style's section of the site editor without appearanceTools. Then, show Appearance Tools being turned on in theme.json code -- or, border controls are a second easy-to-show example. Next, show the 'layout' button that appears after in the site editor. That should help beginners connect some dots!

2. (Quick audio change suggestion) Around the 5:00 mark, consider taking a moment to explain that the comma is important. Beginners (like me!) don't get why that's important, and it's an easy problem to create for yourself 😆

3. (Tougher change: This one is a bit of a headache, but it's important) Around 6:30, the name "Alt Blue" was chosen, which describes the color you will use throughout the demo. You might consider exploring semantic naming conventions (base, contrast, etc. instead of red, green, etc.). I've been told that it's a good idea to use semantic names rather than descriptive. This is important, for example, if a user were to change it from blue to red. The color would still show up as "Alt Blue" even if the color itself was read. I also discovered the hard way that if you try to create a color palette and descriptively name things what you assign them, (i.e. Name: "Black" for Color: "#000000") WordPress prevents that from happening -- the color literally doesn't show up in the site editor! This might be an issue for specific blocks, but I'm not sure, so I thought I would mention it. It looks like that may require some additional changes from 8:00-8:25ish and 9:15-9:28 and 10:16-10:25 to ensure the semantic color name you choose is consistent.

The amount of work and effort you put into making this a clear and useable tutorial is second-to-none, Jonathan. Truly. Thank you for the detailed thought you've put into this!

[jonathanbossenger]

Thank you for the feedback @westnz and @wparasae. I think these are all important, so I'm going to take this out of "review" status, so I can rework this tutorial a little.

[jonathanbossenger]

Side note, after reading through these comments again, I've come to realize that I tend to have a need to "tell" rather than "show" at the start of my tutorials, which is largely useless in a visual format. So going forward, instead of having an "introduction" slide that dumps up a bunch of info, I'm going to take the content of that slide, and split it out into the different sections of the tutorial.

Thanks for helping me highlight this @westnz and @wparasae

[wparasae]

I've come to realize that I tend to have a need to "tell" rather than "show" at the start of my tutorials, which is largely useless in a visual format. So going forward, instead of having an "introduction" slide that dumps up a bunch of info, I'm going to take the content of that slide, and split it out into the different sections of the tutorial.

A thought: This is very much in the style of speeches and essays: Tell your audience what you're going to tell them (intro slides!), tell them what you promised you'd tell them (screencasts!), then tell them what you told them (sum it all up!)! It can definitely be a valuable way to help learners retain knowledge (repetition is important!)

Rather than tossing out your way of doing videos, you might consider keeping your front-loading information style, but adding a few more screencasts as you go -- consider them "teasers" of what they'll learn in the video, perhaps? Like movie previews! :)

[jonathanbossenger]

theme.json-v2.mp4

Version 2 tutorial ready to review @westnz @wparasae

[jonathanbossenger]

A thought: This is very much in the style of speeches and essays: Tell your audience what you're going to tell them (intro slides!), tell them what you promised you'd tell them (screencasts!), then tell them what you told them (sum it all up!)! It can definitely be a valuable way to help learners retain knowledge (repetition is important!)

I don't disagree with this, however, I think the biggest hurdle here is time, if I did all that, my tutorials might end up being too long? 🤔

Don't stop giving me feedback though, it helps me refine and improve. 😄

[jonathanbossenger]

Published - https://learn.wordpress.org/tutorial/introduction-to-theme-json/