[Related Course: Create a Custom Block Theme #1] The Basics of theme.json for New Developers - COURSE Lesson Plan

[wparasae]

IMPORTANT:

** This lesson plan belongs to part of a greater course, Create a Custom Block Theme #1 **
Please reach out to @arasae (Sarah Snow) in the #training team Slack if you would like to help with this lesson plan.

Topic Description

This lesson provides a very high-level overview of theme.json and prepares users to begin writing theme.json code.
It prepares them to write their first line of code.

Objectives

After completing this lesson, participants will be able to:
Updated Objectives: 10/20/22

• Analyze how settings in a theme.json impact the site editor
• Describe how theme.json impacts what options are pre-set in a theme's site editor

Guidelines

Review the [team guidelines] (https://make.wordpress.org/training/handbook/guidelines/)

Development Checklist:

• Review any related material on Learn
• Description and Objectives finalized
• Gather links to Support, other learn.wordpress.org existing resources, and Developer Docs
• Create an outline of the example lesson walk-through
• Draft lesson plan
• Copy edit
• Style guide review
• Instructional Review
• Final review
• Publish
• Announce to the Training team
• Announce to lesson plan creator
• Announce to marketing
• Gather feedback from lesson plan users about the quality

Repo Structure and Lesson Plan Template

Please remove all blockquote comments such as this before publishing.

Description

Have you ever wondered what a theme.json file does? Do you want to learn how to get started coding with theme.json, but weren't sure where to get started? If so, this lesson plan is for you!

Target Audience

Who is this lesson intended for? What interests/skills would they bring? Put an "x" in the brackets for all that apply.

• Users / Content Writers
• Designers
• Beginner-Level Developers
• Developers
• Speakers
• Organizers
• Kids

Experience Level

How much experience would a participant need to get the most from this lesson? Put an "x" in the brackets for all that apply.

• Beginner
• Intermediate
• Advanced

Type of Instruction

Which strategies will be used for this lesson plan? Put an "x" in the brackets for all that apply.

• Text-and-Image-Based, Remote-First Course
• Exercises
• Slides
• [xn (MAYBE IF TIME ALLOWS)] Video Tutorial

Time Estimate (Duration)

How long will it take to present this lesson? Put an "x" in the brackets for the one that applies.

• 1-5 Minutes
• 5-10 Minutes
• 15+ Minutes
• 1 hour or less

Prerequisite Skills

Participants will get the most from this lesson if they have familiarity with:

• The WordPress dashboard
• Installing different themes
• The Schema line in theme.json
• Full Site Editing, especially related to Global Styles
• Coding languages of any sort in the past

Readiness Questions

These are important to include in case someone wants to use this lesson plan in-person as a stand-alone lesson.

1. Are you comfortable navigating the WordPress dashboard?
2. Are you comfortable installing and activating different WordPress themes?
3. Have you experimented with block themes and the Site Editor in the past?
4. Are you familiar with templates, template parts, and the Site Editor?
5. Do you know what “Global Styles” are and why they are helpful to users?
6. Have you ever coded anything in any language before? CSS, HTML, PHP, Java, Javascript, etc?

Slides

If someone wanted to run this lesson as a stand-alone Online Live Workshop or at an in-person WordCamp, you could create slides for this here; if you run a Live Online Workshop on one of these topics or find someone else has, related slides would be welcome!

None Exist Yet

Materials Needed

• Local development environment
• A text editor that supports the 'schema' line, such as VS Studio Code, PHP Storm or Sublime

• A local install of WordPress
• The files for the TwentyTwentyTwo theme
• A starter theme with a blank theme.json and the first few lines filled out (specifically version and schema) - an installable theme that has the very, very basic requirements can be accessed at this link here, in a Google Folder providing resources for this lesson plan. The Zip theme file is called "My Dream Block Theme".

Notes for the Presenter

/Include any tips needed to present this topic for a Live Online Workshop or in an in-person classroom setting.

• Note 1
• Note 2

A list of any handy tips or other information for the presenter.

For example:

• Participants may need to download the TwentySixteen theme before beginning
• What to do if there’s no projector or internet available
• What to do if a participant doesn’t have the necessary set up
• How to handle different opinions about the topic

Lesson Outline

• First do this
• Then move on to this
• Finish with this

The plan for the lesson. Outline form works well.

For example:

• Talk about what a theme is
• Demonstrate how to install and activate a theme
• Practice exercises to have participants find and install a theme on their own site

Exercises

What someone will DO with what they learn in each lesson; most lessons have at least one related exercise.

Exercise name

These help students see the effects of theme.json on their own installation of WordPress, to see the power of how things change.

Appearance Tools:

1. Using the blank theme, navigate to your site editor's global styles. Take note of what options are available.
2. Use your text editor to open the blank theme's theme.json - using schema, open the quotes by typing " and selecting "appearance tools". Set them to true, double-check your theme.json for errors, save, and refresh your site editor. Navigate again to your global styles and answer the first question under the "assessment" section.

Assessment

These assessments will be autograded on Learn.WordPress.org.
There should be one assessment item (or more) for each objective listed above. Each assessment item should support an objective; there should be none that don't.

**1. Which option appears immediately in 'global styles' when you set the appearanceTools to true in your site editor?"
**Double-check this, this whole section needs to be edited -- **
A. Color
B. Typography
C. Layout
D. Headings

Answer: C. Correct answer

**2. A question about what happens under a certain section when you add colors
**3. A question about what happens under another section when you add layout settings

Additional Resources

• To learn more advanced material about theme.json, please visit the WordPress developer handbook here: https://developer.wordpress.org/themes/advanced-topics/theme-json/

Example Lesson [See Script Below]

An example of how the lesson plan can be implemented. Written in script form as one possible way an presenter might use this lesson plan at an event, with screenshots and instructions if necessary.

Section Heading for Example Lesson

You will likely need to break the Example Lesson down into multiple sections.

Lesson Wrap Up

Follow with the Exercises and Assessment outlined above.

[wparasae]

Updating lesson objectives to better fit the flow of the course.

[wparasae]

Needs For Visuals:
-What a block theme's global settings looks like with a bare-bones theme.json (no options -- also existed in the last module, so be aware of that)
-What a block theme's global settings look like with appearance tools turned on (show where these turn off and on)
-What a block theme's global settings look like with a color palette pre-selected
-What changing the colors in a theme.json does to a block theme's global settings
-What removing the colors in a theme.json does in a block theme's global settings (allows them to change it to selections of their choice when they export).
-What it looks like when you just add the color palette in settings
-What it looks like when you create the color palette in settings and also create pre-sets block by block.

Note to self: I'm starting to understand why people use theme.json instead of the site editor. It's a matter of speed. We might want to consider at the end of this, creating a module called "developer shortcuts" that dive into why using settings and styles saves developers time overall, to help that click into place.

[wparasae]

Essential questions for a video:
Some essential questions I'm generating around this are:

1. Why would developers want to turn global settings off and on for a client?
2. When a theme is first installed, some themes have certain colors pre-set.

• Where do these colors come from?
• How can these colors be pre-set in certain blocks or elements of a site?

[wparasae]

Script/Text for Potential Tutorial: "An Overview of theme.json for Beginners"

Mini-Lesson / Workshop: Hook (Attention Grabber / Background Activator)

Have you ever noticed that some themes have more options available to you than others?
(Visual: Theme with appearance tools turned on vs. theme with appearance tools turned off) Resource: 1st Half of This Video

Have you ever wondered why some block themes come with pre-selected colors, and others do not?
(Visual: 2022 Theme with Color Presets vs. bare bones block theme without a theme.json) (Resource: 2nd Half of This Video)

When you compare new-to-you, uncustomized themes that you just installed from the WordPress repository, you may have noticed differences in all sort of things, such as colors, font sizes, gradients, duotones, default widths for general vs. wide content, and more. You can see in this example that the colors blue and yellow have been pre-selected for this cover block (example) Where do these defaults come from, and how are they set? (example video here)

The short answer can be found in one of a block theme's configuration files, called the "theme.json". This file is one way developers efficiently set defaults, such as which colors exist when a user first installs a theme, how big, small, or capitalized a theme's text starts out as, or even how much space or padding exists around different elements of the site. (Video Resource for this section)

The good new for non-coders is that the site editor allows you to select many of these options with a few clicks of a button, no code required. (Video example of point and click site editor)

The bad news is that not every option you can utilize in a theme.json file currently exists in the site editor -- for example, specific customization options over header sizes, capitalization, or line spacing is not available yet in the site editor and must be coded in your theme's theme.json. (Example of option that doesn't exist in site editor)

This theme.json file also helps developers centralize their choices in one place, so if they wanted to make a big, sweeping change to their theme, they can head to their theme.json file . For example, in the twenty-twenty-two theme, you can see that this color palette has been pre-set with specific colors (NAME THE COLORS AND FIND THEM). The 'styles' section of a theme.json allows developers to apply a previously selected color, size, or ELEMENTWHATARETHESECALLED and apply it to another part of the site, or a specific block. To see this in action, watch me change this one color from black (which has the hexadecimal color code #000000) to white, which uses the code #ff0000 to tell WordPress what color to display on your screen. You'll see that not only did this change the color in the palette, but it also rippled through the website; any time the developer wanted this primary color used, by changing it in this one centralized place in the theme.json, the color is automatically applied everywhere else.

You'll notice that this option is in the site editor. You can also change the color using this color picker, and the changes will ripple throughout your site, wherever this has been specific in the theme's theme.json. It's a great shortcut to being able to rebrand a website fast!

This following portion should probably be moved to another section to keep this 'chunked' Maybe this would make for a good exercise perhaps?
There's a lot to learn about theme.json. Where is an easy way to start exploring?

First, we always recommend using the theme.json schema to help you code in theme.json.

(FYI here's a handy site that explains what json schema is, and how it works https://json-schema.org/) -- please see the "Using Schema with WordPress theme.json" tutorial for more. Second, you might start with turning some basic settings off and on, such as AppearanceTools.

Other beginning-level theme.json codes you might explore are:

• Color (specifically palette).
• Layout settings "contentSize" and "wideSize" can help you get a strong feel for toggling options off an on in both your global styles and in individual block settings as well. <--Note to Sarah, need to chat with Jonathan or someone else more familiar with layout settings for this section.

To learn more advanced material about theme.json, please visit the WordPress developer handbook here: https://developer.wordpress.org/themes/advanced-topics/theme-json/

[wparasae]

Update: Still gathering visuals. I think I need to add some course-specific information in here as well, so it's not exactly a stand-alone lesson plan, but I suppose I could put that in the course module itself rather than here in order to make this a lesson plan all on its own maybe?

Either way, Module 3, Lesson 1 is in progress; I anticipate starting on Lesson 2 (which is turning on appearance tools, setting appearance width, and MAYBE setting a color palette ahead of time) tomorrow, but we'll see.

[jonathanbossenger]

@wparasae looks good, I just have a few suggestions.

and must be coded using javascript in your theme's theme.json.
While I agree that JSON is JavaScript Object Notation, I personally wouldn't call the code in theme.json JavaScript, just because it might put folks off. I'd just say `must be coded in your theme's theme.json.

First, we always recommend using a schema line to help you code in theme.json
I would reword this slightly

First, we always recommend using the theme.json schema to help you code in theme.json.

(FYI here's a handy site that explains what json schema is, and how it works https://json-schema.org/)

[wparasae]

Change has been made. Thank you for that review and insight, Jonathan!

[wparasae]

The following lesson is ready for review:

1. The Basics of theme.json for New Developers - Review Module 3, Lesson 1 Here / Leave Feedback for Module 3, Lesson 1 Here is ready for review.

Specific Questions For Feedback (Leave all feedback for this lesson in a comment on this issue)
a. Is the content correct? Are there any errors?
b. Is the content too long / too short / just right? Why or why not?
c. What revisions might you suggest for added clarity?

Please leave any feedback for this module in a comment on this post.

[westnz]

Review:

• Love how you ask questions to make the learner think and draw their attention
• The screenshots are very effective
• Twenty Twenty-Three instead of Twenty Twenty Three
• Should 'site editor' be in capital letters?
• Very clever and helpful = What can your theme.json do? So many things!
• Just something I thought I'll mention. I remember someone said that putting text in bold to highlight is not helpful for accessibility: https://help.siteimprove.com/support/solutions/articles/80000448460-accessibility-the-use-of-emphasis-in-text
• The dropdown block is very cool / interactive.
• Add a hyphen between brand-new:

[wparasae]

Changes made; I also removed (some, but not all) extra bolding and added "Important!" per the guide you linked. Excellent resource, Wes!

[kaitohm]

Closing in favor of prioritizing Learning Pathways content.