Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add description for templateParts in theme json. #30118

Merged
merged 4 commits into from
Mar 26, 2021

Conversation

Addison-Stavlo
Copy link
Contributor

Description

Updates theme json docs to include schema for definine template part areas.

How has this been tested?

Screenshots

Types of changes

Checklist:

  • My code is tested.
  • My code follows the WordPress code style.
  • My code follows the accessibility standards.
  • I've tested my changes with keyboard and screen readers.
  • My code has proper inline documentation.
  • I've included developer documentation if appropriate.
  • I've updated all React Native files affected by any refactorings/renamings in this PR.

@github-actions
Copy link

github-actions bot commented Mar 22, 2021

Size Change: +9.4 kB (+1%)

Total Size: 1.42 MB

Filename Size Change
build/api-fetch/index.js 3.41 kB +8 B (0%)
build/autop/index.js 2.82 kB +2 B (0%)
build/blob/index.js 665 B +1 B (0%)
build/block-directory/index.js 8.63 kB +5 B (0%)
build/block-editor/index.js 127 kB +559 B (0%)
build/block-editor/style-rtl.css 12.4 kB -8 B (0%)
build/block-editor/style.css 12.4 kB -9 B (0%)
build/block-library/blocks/columns/style-rtl.css 436 B +15 B (+4%)
build/block-library/blocks/columns/style.css 435 B +14 B (+3%)
build/block-library/blocks/cover/style-rtl.css 1.23 kB -11 B (-1%)
build/block-library/blocks/cover/style.css 1.23 kB -12 B (-1%)
build/block-library/blocks/file/editor-rtl.css 175 B -24 B (-12%) 👏
build/block-library/blocks/file/editor.css 174 B -24 B (-12%) 👏
build/block-library/blocks/freeform/editor-rtl.css 2.44 kB -15 B (-1%)
build/block-library/blocks/freeform/editor.css 2.44 kB -15 B (-1%)
build/block-library/blocks/gallery/style-rtl.css 1.09 kB -14 B (-1%)
build/block-library/blocks/gallery/style.css 1.09 kB -15 B (-1%)
build/block-library/blocks/latest-comments/editor-rtl.css 0 B -159 B (removed) 🏆
build/block-library/blocks/latest-comments/editor.css 0 B -158 B (removed) 🏆
build/block-library/blocks/list/editor-rtl.css 0 B -65 B (removed) 🏆
build/block-library/blocks/list/editor.css 0 B -65 B (removed) 🏆
build/block-library/blocks/navigation-link/editor-rtl.css 634 B +8 B (+1%)
build/block-library/blocks/navigation-link/editor.css 635 B +8 B (+1%)
build/block-library/blocks/navigation-link/style-rtl.css 908 B +223 B (+33%) 🚨
build/block-library/blocks/navigation-link/style.css 908 B +226 B (+33%) 🚨
build/block-library/blocks/navigation/editor-rtl.css 1.13 kB +17 B (+2%)
build/block-library/blocks/navigation/editor.css 1.13 kB +16 B (+1%)
build/block-library/blocks/page-list/style-rtl.css 167 B -370 B (-69%) 🏆
build/block-library/blocks/page-list/style.css 167 B -369 B (-69%) 🏆
build/block-library/blocks/quote/editor-rtl.css 0 B -61 B (removed) 🏆
build/block-library/blocks/quote/editor.css 0 B -61 B (removed) 🏆
build/block-library/blocks/video/style-rtl.css 173 B -14 B (-7%)
build/block-library/blocks/video/style.css 173 B -14 B (-7%)
build/block-library/editor-rtl.css 9.54 kB +68 B (+1%)
build/block-library/editor.css 9.53 kB +55 B (+1%)
build/block-library/index.js 151 kB +3.52 kB (+2%)
build/block-library/reset-rtl.css 383 B +9 B (+2%)
build/block-library/reset.css 384 B +8 B (+2%)
build/block-library/style-rtl.css 8.96 kB +72 B (+1%)
build/block-library/style.css 8.96 kB +71 B (+1%)
build/block-library/theme-rtl.css 694 B -6 B (-1%)
build/block-library/theme.css 696 B -5 B (-1%)
build/blocks/index.js 48.3 kB +9 B (0%)
build/components/index.js 286 kB +1.91 kB (+1%)
build/components/style-rtl.css 16.2 kB -5 B (0%)
build/components/style.css 16.2 kB -4 B (0%)
build/compose/index.js 11.2 kB +97 B (+1%)
build/core-data/index.js 16.8 kB +42 B (0%)
build/customize-widgets/index.js 6.03 kB +46 B (+1%)
build/data-controls/index.js 838 B +7 B (+1%)
build/data/index.js 8.87 kB +4 B (0%)
build/date/index.js 31.9 kB +22 B (0%)
build/dom/index.js 4.98 kB +8 B (0%)
build/edit-navigation/index.js 17 kB +5.11 kB (+43%) 🚨
build/edit-navigation/style-rtl.css 2.68 kB +1.27 kB (+90%) 🆘
build/edit-navigation/style.css 2.68 kB +1.28 kB (+91%) 🆘
build/edit-post/index.js 307 kB -459 B (0%)
build/edit-post/style-rtl.css 7.04 kB -12 B (0%)
build/edit-post/style.css 7.03 kB -12 B (0%)
build/edit-site/index.js 27.5 kB +298 B (+1%)
build/edit-site/style-rtl.css 4.5 kB -5 B (0%)
build/edit-site/style.css 4.5 kB -4 B (0%)
build/edit-widgets/index.js 15.6 kB -4.53 kB (-22%) 🎉
build/edit-widgets/style-rtl.css 2.97 kB -168 B (-5%)
build/edit-widgets/style.css 2.98 kB -168 B (-5%)
build/editor/index.js 42.7 kB +866 B (+2%)
build/editor/style-rtl.css 3.95 kB +47 B (+1%)
build/editor/style.css 3.95 kB +47 B (+1%)
build/element/index.js 4.61 kB +7 B (0%)
build/format-library/index.js 6.75 kB +1 B (0%)
build/hooks/index.js 2.28 kB +1 B (0%)
build/i18n/index.js 4.01 kB -1 B (0%)
build/keyboard-shortcuts/index.js 2.53 kB +5 B (0%)
build/keycodes/index.js 1.95 kB -1 B (0%)
build/list-reusable-blocks/index.js 3.19 kB +48 B (+2%)
build/media-utils/index.js 5.38 kB +42 B (+1%)
build/notices/index.js 1.85 kB -1 B (0%)
build/nux/index.js 3.42 kB +8 B (0%)
build/plugins/index.js 2.95 kB +61 B (+2%)
build/priority-queue/index.js 790 B -1 B (0%)
build/react-i18n/index.js 1.46 kB +2 B (0%)
build/redux-routine/index.js 2.84 kB +4 B (0%)
build/rich-text/index.js 13.5 kB +126 B (+1%)
build/server-side-render/index.js 2.59 kB +10 B (0%)
build/shortcode/index.js 1.7 kB -1 B (0%)
build/token-list/index.js 1.27 kB -2 B (0%)
build/url/index.js 3.02 kB -1 B (0%)
build/wordcount/index.js 1.22 kB -1 B (0%)
ℹ️ View Unchanged
Filename Size Change
build/a11y/index.js 1.14 kB 0 B
build/annotations/index.js 3.77 kB 0 B
build/block-directory/style-rtl.css 1 kB 0 B
build/block-directory/style.css 1.01 kB 0 B
build/block-library/blocks/archives/editor-rtl.css 61 B 0 B
build/block-library/blocks/archives/editor.css 60 B 0 B
build/block-library/blocks/audio/editor-rtl.css 58 B 0 B
build/block-library/blocks/audio/editor.css 58 B 0 B
build/block-library/blocks/audio/style-rtl.css 112 B 0 B
build/block-library/blocks/audio/style.css 112 B 0 B
build/block-library/blocks/block/editor-rtl.css 161 B 0 B
build/block-library/blocks/block/editor.css 161 B 0 B
build/block-library/blocks/button/editor-rtl.css 475 B 0 B
build/block-library/blocks/button/editor.css 474 B 0 B
build/block-library/blocks/button/style-rtl.css 479 B 0 B
build/block-library/blocks/button/style.css 479 B 0 B
build/block-library/blocks/buttons/editor-rtl.css 315 B 0 B
build/block-library/blocks/buttons/editor.css 315 B 0 B
build/block-library/blocks/buttons/style-rtl.css 364 B 0 B
build/block-library/blocks/buttons/style.css 363 B 0 B
build/block-library/blocks/calendar/style-rtl.css 208 B 0 B
build/block-library/blocks/calendar/style.css 208 B 0 B
build/block-library/blocks/categories/editor-rtl.css 84 B 0 B
build/block-library/blocks/categories/editor.css 83 B 0 B
build/block-library/blocks/categories/style-rtl.css 79 B 0 B
build/block-library/blocks/categories/style.css 79 B 0 B
build/block-library/blocks/code/style-rtl.css 90 B 0 B
build/block-library/blocks/code/style.css 90 B 0 B
build/block-library/blocks/columns/editor-rtl.css 190 B 0 B
build/block-library/blocks/columns/editor.css 190 B 0 B
build/block-library/blocks/cover/editor-rtl.css 605 B 0 B
build/block-library/blocks/cover/editor.css 605 B 0 B
build/block-library/blocks/embed/editor-rtl.css 486 B 0 B
build/block-library/blocks/embed/editor.css 486 B 0 B
build/block-library/blocks/embed/style-rtl.css 401 B 0 B
build/block-library/blocks/embed/style.css 400 B 0 B
build/block-library/blocks/file/style-rtl.css 248 B 0 B
build/block-library/blocks/file/style.css 248 B 0 B
build/block-library/blocks/gallery/editor-rtl.css 704 B 0 B
build/block-library/blocks/gallery/editor.css 705 B 0 B
build/block-library/blocks/group/editor-rtl.css 160 B 0 B
build/block-library/blocks/group/editor.css 160 B 0 B
build/block-library/blocks/group/style-rtl.css 57 B 0 B
build/block-library/blocks/group/style.css 57 B 0 B
build/block-library/blocks/heading/editor-rtl.css 129 B 0 B
build/block-library/blocks/heading/editor.css 129 B 0 B
build/block-library/blocks/heading/style-rtl.css 76 B 0 B
build/block-library/blocks/heading/style.css 76 B 0 B
build/block-library/blocks/html/editor-rtl.css 281 B 0 B
build/block-library/blocks/html/editor.css 281 B 0 B
build/block-library/blocks/image/editor-rtl.css 717 B 0 B
build/block-library/blocks/image/editor.css 716 B 0 B
build/block-library/blocks/image/style-rtl.css 476 B 0 B
build/block-library/blocks/image/style.css 478 B 0 B
build/block-library/blocks/latest-comments/style-rtl.css 269 B 0 B
build/block-library/blocks/latest-comments/style.css 269 B 0 B
build/block-library/blocks/latest-posts/editor-rtl.css 137 B 0 B
build/block-library/blocks/latest-posts/editor.css 137 B 0 B
build/block-library/blocks/latest-posts/style-rtl.css 523 B 0 B
build/block-library/blocks/latest-posts/style.css 522 B 0 B
build/block-library/blocks/legacy-widget/editor-rtl.css 398 B 0 B
build/block-library/blocks/legacy-widget/editor.css 399 B 0 B
build/block-library/blocks/list/style-rtl.css 63 B 0 B
build/block-library/blocks/list/style.css 63 B 0 B
build/block-library/blocks/media-text/editor-rtl.css 191 B 0 B
build/block-library/blocks/media-text/editor.css 191 B 0 B
build/block-library/blocks/media-text/style-rtl.css 535 B 0 B
build/block-library/blocks/media-text/style.css 532 B 0 B
build/block-library/blocks/more/editor-rtl.css 434 B 0 B
build/block-library/blocks/more/editor.css 434 B 0 B
build/block-library/blocks/navigation/style-rtl.css 204 B 0 B
build/block-library/blocks/navigation/style.css 205 B 0 B
build/block-library/blocks/nextpage/editor-rtl.css 395 B 0 B
build/block-library/blocks/nextpage/editor.css 395 B 0 B
build/block-library/blocks/page-list/editor-rtl.css 170 B 0 B
build/block-library/blocks/page-list/editor.css 170 B 0 B
build/block-library/blocks/paragraph/editor-rtl.css 157 B 0 B
build/block-library/blocks/paragraph/editor.css 157 B 0 B
build/block-library/blocks/paragraph/style-rtl.css 247 B 0 B
build/block-library/blocks/paragraph/style.css 248 B 0 B
build/block-library/blocks/post-author/editor-rtl.css 209 B 0 B
build/block-library/blocks/post-author/editor.css 209 B 0 B
build/block-library/blocks/post-author/style-rtl.css 183 B 0 B
build/block-library/blocks/post-author/style.css 184 B 0 B
build/block-library/blocks/post-comments-form/style-rtl.css 250 B 0 B
build/block-library/blocks/post-comments-form/style.css 250 B 0 B
build/block-library/blocks/post-content/editor-rtl.css 139 B 0 B
build/block-library/blocks/post-content/editor.css 139 B 0 B
build/block-library/blocks/post-excerpt/editor-rtl.css 73 B 0 B
build/block-library/blocks/post-excerpt/editor.css 73 B 0 B
build/block-library/blocks/post-featured-image/editor-rtl.css 338 B 0 B
build/block-library/blocks/post-featured-image/editor.css 338 B 0 B
build/block-library/blocks/post-featured-image/style-rtl.css 100 B 0 B
build/block-library/blocks/post-featured-image/style.css 100 B 0 B
build/block-library/blocks/preformatted/style-rtl.css 63 B 0 B
build/block-library/blocks/preformatted/style.css 63 B 0 B
build/block-library/blocks/pullquote/editor-rtl.css 183 B 0 B
build/block-library/blocks/pullquote/editor.css 183 B 0 B
build/block-library/blocks/pullquote/style-rtl.css 318 B 0 B
build/block-library/blocks/pullquote/style.css 318 B 0 B
build/block-library/blocks/query-loop/editor-rtl.css 83 B 0 B
build/block-library/blocks/query-loop/editor.css 82 B 0 B
build/block-library/blocks/query-loop/style-rtl.css 315 B 0 B
build/block-library/blocks/query-loop/style.css 317 B 0 B
build/block-library/blocks/query-pagination-numbers/editor-rtl.css 122 B 0 B
build/block-library/blocks/query-pagination-numbers/editor.css 121 B 0 B
build/block-library/blocks/query-pagination/editor-rtl.css 270 B 0 B
build/block-library/blocks/query-pagination/editor.css 262 B 0 B
build/block-library/blocks/query-pagination/style-rtl.css 168 B 0 B
build/block-library/blocks/query-pagination/style.css 168 B 0 B
build/block-library/blocks/query-title/editor-rtl.css 86 B 0 B
build/block-library/blocks/query-title/editor.css 86 B 0 B
build/block-library/blocks/query/editor-rtl.css 795 B 0 B
build/block-library/blocks/query/editor.css 794 B 0 B
build/block-library/blocks/quote/style-rtl.css 169 B 0 B
build/block-library/blocks/quote/style.css 169 B 0 B
build/block-library/blocks/rss/editor-rtl.css 201 B 0 B
build/block-library/blocks/rss/editor.css 202 B 0 B
build/block-library/blocks/rss/style-rtl.css 290 B 0 B
build/block-library/blocks/rss/style.css 290 B 0 B
build/block-library/blocks/search/editor-rtl.css 165 B 0 B
build/block-library/blocks/search/editor.css 165 B 0 B
build/block-library/blocks/search/style-rtl.css 342 B 0 B
build/block-library/blocks/search/style.css 344 B 0 B
build/block-library/blocks/separator/editor-rtl.css 99 B 0 B
build/block-library/blocks/separator/editor.css 99 B 0 B
build/block-library/blocks/separator/style-rtl.css 236 B 0 B
build/block-library/blocks/separator/style.css 236 B 0 B
build/block-library/blocks/shortcode/editor-rtl.css 512 B 0 B
build/block-library/blocks/shortcode/editor.css 512 B 0 B
build/block-library/blocks/site-logo/editor-rtl.css 201 B 0 B
build/block-library/blocks/site-logo/editor.css 201 B 0 B
build/block-library/blocks/site-logo/style-rtl.css 115 B 0 B
build/block-library/blocks/site-logo/style.css 115 B 0 B
build/block-library/blocks/social-link/editor-rtl.css 164 B 0 B
build/block-library/blocks/social-link/editor.css 165 B 0 B
build/block-library/blocks/social-links/editor-rtl.css 776 B 0 B
build/block-library/blocks/social-links/editor.css 776 B 0 B
build/block-library/blocks/social-links/style-rtl.css 1.32 kB 0 B
build/block-library/blocks/social-links/style.css 1.33 kB 0 B
build/block-library/blocks/spacer/editor-rtl.css 317 B 0 B
build/block-library/blocks/spacer/editor.css 317 B 0 B
build/block-library/blocks/spacer/style-rtl.css 48 B 0 B
build/block-library/blocks/spacer/style.css 48 B 0 B
build/block-library/blocks/table/editor-rtl.css 478 B 0 B
build/block-library/blocks/table/editor.css 478 B 0 B
build/block-library/blocks/table/style-rtl.css 402 B 0 B
build/block-library/blocks/table/style.css 402 B 0 B
build/block-library/blocks/tag-cloud/editor-rtl.css 118 B 0 B
build/block-library/blocks/tag-cloud/editor.css 118 B 0 B
build/block-library/blocks/tag-cloud/style-rtl.css 94 B 0 B
build/block-library/blocks/tag-cloud/style.css 94 B 0 B
build/block-library/blocks/template-part/editor-rtl.css 552 B 0 B
build/block-library/blocks/template-part/editor.css 551 B 0 B
build/block-library/blocks/term-description/editor-rtl.css 90 B 0 B
build/block-library/blocks/term-description/editor.css 90 B 0 B
build/block-library/blocks/text-columns/editor-rtl.css 95 B 0 B
build/block-library/blocks/text-columns/editor.css 95 B 0 B
build/block-library/blocks/text-columns/style-rtl.css 166 B 0 B
build/block-library/blocks/text-columns/style.css 166 B 0 B
build/block-library/blocks/verse/editor-rtl.css 50 B 0 B
build/block-library/blocks/verse/editor.css 50 B 0 B
build/block-library/blocks/verse/style-rtl.css 87 B 0 B
build/block-library/blocks/verse/style.css 87 B 0 B
build/block-library/blocks/video/editor-rtl.css 504 B 0 B
build/block-library/blocks/video/editor.css 503 B 0 B
build/block-library/common-rtl.css 1.1 kB 0 B
build/block-library/common.css 1.1 kB 0 B
build/block-serialization-default-parser/index.js 1.87 kB 0 B
build/block-serialization-spec-parser/index.js 3.06 kB 0 B
build/customize-widgets/style-rtl.css 378 B 0 B
build/customize-widgets/style.css 379 B 0 B
build/deprecated/index.js 787 B 0 B
build/dom-ready/index.js 577 B 0 B
build/escape-html/index.js 735 B 0 B
build/format-library/style-rtl.css 637 B 0 B
build/format-library/style.css 639 B 0 B
build/html-entities/index.js 622 B 0 B
build/is-shallow-equal/index.js 699 B 0 B
build/list-reusable-blocks/style-rtl.css 629 B 0 B
build/list-reusable-blocks/style.css 628 B 0 B
build/nux/style-rtl.css 731 B 0 B
build/nux/style.css 727 B 0 B
build/primitives/index.js 1.42 kB 0 B
build/reusable-blocks/index.js 3.78 kB 0 B
build/reusable-blocks/style-rtl.css 225 B 0 B
build/reusable-blocks/style.css 225 B 0 B
build/viewport/index.js 1.86 kB 0 B
build/warning/index.js 1.14 kB 0 B

compressed-size-action

Copy link
Contributor

@ntsekouras ntsekouras left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @Addison-Stavlo !

Something that I'm not sure myself is: do we need to declare all created Template parts in theme.json or we have to, only if we want to utilize the Block variations API?

@@ -464,6 +464,19 @@ There's a growing need to add more theme metadata to the theme.json. This sectio
}
```

**templateParts**: within this field themes can list the template parts present in the `block-template-parts` folder. For example, for a template part named `my-template-part.html`, the `theme.json` can declare what area that template part is intended for to use the corresponding block variation in the editor. Currently block variations exist for "header" and "footer" values of the area term, any other values and undefined template parts will default to the general template part block.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it needs a bit more clarification about why this has to be set here (theme.json) and not as an attribute in the markup. Maybe something like this:
the Template part block renders its own entity internally. Any attributes on the outer block itself are just block attributes, and thus saved as part of the post it is a child of (template, page, etc). - you have written this :).

Also a bit more info about what a match with a block variation means (results), like the proper display information and where else will be used for (semantic).

Copy link
Contributor Author

@Addison-Stavlo Addison-Stavlo Mar 23, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we need to declare all created Template parts in theme.json or we have to, only if we want to utilize the Block variations API?

We don't have to declare them, as they would default to the general/uncategorized area. Thats part of what I was getting at with:

undefined template parts will default to the general template part block.


I think it needs a bit more clarification about why this has to be set here (theme.json) and not as an attribute in the markup.

I was trying to keep it light, describing what needs to be done and how to do it without adding all the weight of internal database structures, entities, taxonomy terms, etc. etc. Im happy to add more if people think it is necessary, but I was trying to avoid making the description a bit too heavy and confusing.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and not as an attribute in the markup.

Thinking about it more, especially since we recently added that 'area' attribute used in placeholder/creation flows it probably makes sense to clarify that here. 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated a bit 😁

@gziolo gziolo changed the title Add description for templateParts in theme json. Docs: Add description for templateParts in theme json. Mar 23, 2021
@gziolo gziolo added the [Feature] Themes Questions or issues with incorporating or styling blocks in a theme. label Mar 23, 2021
Copy link
Contributor

@carolinan carolinan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the first passage I got confused about why the term "block variation" was used, but it was made clearer when I continued reading.

@Addison-Stavlo
Copy link
Contributor Author

Thanks for taking a look @carolinan!

In the first passage I got confused about why the term "block variation" was used, but it was made clearer when I continued reading.

Im glad it became more clear. I pushed a minor update to try and improve clarity, hopefully that is slightly better. 😁 If you have any other suggestions I am happy to hear them.

Copy link
Contributor

@ntsekouras ntsekouras left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

Copy link
Member

@david-szabo97 david-szabo97 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚀

@ntsekouras ntsekouras merged commit 7b96d88 into trunk Mar 26, 2021
@ntsekouras ntsekouras deleted the add/template-parts-theme-json-doc branch March 26, 2021 11:08
@github-actions github-actions bot added this to the Gutenberg 10.4 milestone Mar 26, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Feature] Themes Questions or issues with incorporating or styling blocks in a theme. [Type] Developer Documentation Documentation for developers
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants