From 545e48e05af8c1598960d71961f1bfc18a67bbb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Albert=20Juh=C3=A9=20Lluveras?= Date: Tue, 11 Jun 2024 10:04:48 +0200 Subject: [PATCH] Expand block templates documentation (#48247) * Expand block templates documentation * Add changelog file * New manifest * Minor changes * Add Page: Coming soon template --- docs/docs-manifest.json | 28 ++-- docs/theme-development/README.md | 2 + .../classic-theme-developer-handbook.md | 2 +- docs/theme-development/image-sizes.md | 2 +- .../theme-development/set-up-a-child-theme.md | 2 +- docs/theme-development/template-structure.md | 6 +- .../docs/designers/theming/README.md | 128 +++++++----------- .../designers/theming/cart-and-checkout.md | 3 +- .../docs/designers/theming/css-styling.md | 80 +++++++++++ .../docs/designers/theming/filter-blocks.md | 3 +- .../update-block-templates-documentation | 4 + 11 files changed, 160 insertions(+), 100 deletions(-) create mode 100644 plugins/woocommerce-blocks/docs/designers/theming/css-styling.md create mode 100644 plugins/woocommerce/changelog/update-block-templates-documentation diff --git a/docs/docs-manifest.json b/docs/docs-manifest.json index b164246bed3..d6e15f5298d 100644 --- a/docs/docs-manifest.json +++ b/docs/docs-manifest.json @@ -972,7 +972,7 @@ "categories": [] }, { - "content": "\nLearn to design and integrate custom themes in WooCommerce, focusing on responsive design and ecommerce optimization.\n", + "content": "\nLearn to design and integrate custom themes in WooCommerce, focusing on responsive design and ecommerce optimization.\n\nThis document was created for use when developing classic themes. Check this other document for [block theme development](../../plugins/woocommerce-blocks/docs/designers/theming/README.md).\n", "category_slug": "theme-development", "category_title": "Theme Development", "posts": [ @@ -996,28 +996,35 @@ { "post_title": "Template structure & Overriding templates via a theme", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/theme-development/template-structure.md", - "hash": "e96f02bb6256e7f80bbe5bf5fa2b5006dd0d49cd67c8825414a64a6e34d0768a", + "hash": "6099b3a45f91390d9dd239f496eaf531be2b638c666858d6a066051ce915176a", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/theme-development/template-structure.md", - "id": "34bfebec9fc45e680976814928a7b8a1778af14e" + "id": "34bfebec9fc45e680976814928a7b8a1778af14e", + "links": { + "../../plugins/woocommerce-blocks/docs/designers/theming/README.md": "64ff2179eb307d2bcd8d9736b3249ca56b77ba0c" + } }, { "post_title": "How to set up and use a child theme", "menu_title": "Set up and use a child theme", "tags": "how-to", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/theme-development/set-up-a-child-theme.md", - "hash": "78e003139277d0e47b71921d64fd7c3225a8ada819f0989e1c0a605ac3d2e2f7", + "hash": "b362d5ddd34d8b81f6a2ee2369dd2cd68e51700836a85f96d629e87d564b0844", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/theme-development/set-up-a-child-theme.md", - "id": "00b6916595cbde7766f080260a9ea26f53f3271c" + "id": "00b6916595cbde7766f080260a9ea26f53f3271c", + "links": { + "../../plugins/woocommerce-blocks/docs/designers/theming/README.md": "64ff2179eb307d2bcd8d9736b3249ca56b77ba0c" + } }, { "post_title": "Image sizing for theme developers", "menu_title": "Image sizing", "tags": "reference", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/theme-development/image-sizes.md", - "hash": "c0c60cfd163c9fe935f1a6a8d1934eaf118668dd411212001f7f9f35a5cdcc8d", + "hash": "ff26ee246bb3d2f70c0fdc6dcedf50b9ef7bc55442c4378325880117f85025cd", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/theme-development/image-sizes.md", "id": "3f5301ac3040d38bc449b440733da6a466209df3", "links": { + "../../plugins/woocommerce-blocks/docs/designers/theming/README.md": "64ff2179eb307d2bcd8d9736b3249ca56b77ba0c", "./thumbnail-image-regeneration.md": "733e1b16276d64f128ba0e337ca68ec3de0bf68f" } }, @@ -1043,9 +1050,12 @@ "post_title": "Classic theme development handbook", "menu_title": "Classic theme development", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/theme-development/classic-theme-developer-handbook.md", - "hash": "5b39b6db8ab9f08b8270e5803e19ee2abf6fc0fc6458780447fd8b24213d3100", + "hash": "1194437fbc2ec82d60c8b73a9742ec650bd90fe734758c3a2b27ed852d4d14f7", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/theme-development/classic-theme-developer-handbook.md", - "id": "c2fde53e1dc3efbded3cfe1fb4df27136a3799a4" + "id": "c2fde53e1dc3efbded3cfe1fb4df27136a3799a4", + "links": { + "../../plugins/woocommerce-blocks/docs/designers/theming/README.md": "64ff2179eb307d2bcd8d9736b3249ca56b77ba0c" + } } ], "categories": [] @@ -1349,5 +1359,5 @@ "categories": [] } ], - "hash": "1579358bdc138f095c65a591f1e4e8ad32529375fff451d3f06e1deeeb035956" + "hash": "04ed3ebda992e9548c692aa676e14bda41d40d4c89d3c9aafd3edb63809e4651" } \ No newline at end of file diff --git a/docs/theme-development/README.md b/docs/theme-development/README.md index 2b43d243569..ee0a9487fe3 100644 --- a/docs/theme-development/README.md +++ b/docs/theme-development/README.md @@ -5,3 +5,5 @@ post_title: Theme Development --- Learn to design and integrate custom themes in WooCommerce, focusing on responsive design and ecommerce optimization. + +This document was created for use when developing classic themes. Check this other document for [block theme development](../../plugins/woocommerce-blocks/docs/designers/theming/README.md). diff --git a/docs/theme-development/classic-theme-developer-handbook.md b/docs/theme-development/classic-theme-developer-handbook.md index e725fb20bc8..dcdd64c0b6f 100644 --- a/docs/theme-development/classic-theme-developer-handbook.md +++ b/docs/theme-development/classic-theme-developer-handbook.md @@ -5,7 +5,7 @@ menu_title: Classic theme development --- -**Note:** this document is geared toward the development of classic themes. For the recommended modern approach, visit [Develop Your First Low-Code Block Theme](https://learn.wordpress.org/course/develop-your-first-low-code-block-theme/) to learn about block theme development, and explore the [Create Block Theme plugin](https://wordpress.org/plugins/create-block-theme/) tool when you're ready to create a new theme. +**Note:** this document is geared toward the development of classic themes. Check this other document for [block theme development](../../plugins/woocommerce-blocks/docs/designers/theming/README.md). --- diff --git a/docs/theme-development/image-sizes.md b/docs/theme-development/image-sizes.md index bf4517edac5..62f20211aed 100644 --- a/docs/theme-development/image-sizes.md +++ b/docs/theme-development/image-sizes.md @@ -4,7 +4,7 @@ menu_title: Image sizing tags: reference --- -**Note:** this document was created for use when developing classic themes (as opposed to block themes). +**Note:** this document was created for use when developing classic themes (as opposed to block themes). Check this other document for [block theme development](../../plugins/woocommerce-blocks/docs/designers/theming/README.md). To display images in your catalog, WooCommerce registers a few image sizes which define the actual image dimensions to be used. These sizes include: diff --git a/docs/theme-development/set-up-a-child-theme.md b/docs/theme-development/set-up-a-child-theme.md index c7f5bff7f1c..b91e8beb867 100644 --- a/docs/theme-development/set-up-a-child-theme.md +++ b/docs/theme-development/set-up-a-child-theme.md @@ -4,7 +4,7 @@ menu_title: Set up and use a child theme tags: how-to --- -**Note:** This document is intended for creating and using classic child themes. For a comprehensive guide on creating a child block theme and understanding the differences between a classic and block theme, please refer to [this detailed documentation](https://learn.wordpress.org/lesson-plan/create-a-basic-child-theme-for-block-themes/). +**Note:** This document is intended for creating and using classic child themes. For a comprehensive guide on creating a child block theme and understanding the differences between a classic and block theme, please refer to [WooCommerce block theme development](../../plugins/woocommerce-blocks/docs/designers/theming/README.md) and [WordPress block child theme development](https://learn.wordpress.org/lesson-plan/create-a-basic-child-theme-for-block-themes/). Sometimes, you might need to customize your theme or WooCommerce beyond what is possible via the options. These guidelines will teach you the basics of how to go about customizing your site by using a child theme. diff --git a/docs/theme-development/template-structure.md b/docs/theme-development/template-structure.md index 53bb8694fe7..cb1b51aa6e7 100644 --- a/docs/theme-development/template-structure.md +++ b/docs/theme-development/template-structure.md @@ -4,11 +4,7 @@ post_title: Template structure & Overriding templates via a theme --- -**Note:** this document is geared toward template development for classic themes. For the recommended modern approach, -visit [Develop Your First Low-Code Block Theme](https://learn.wordpress.org/course/develop-your-first-low-code-block-theme/) -to learn about block theme development, and explore -the [Create Block Theme plugin](https://wordpress.org/plugins/create-block-theme/) tool when you're ready to create a -new theme. +**Note:** this document is geared toward template development for classic themes. Check this other document for [block theme development](../../plugins/woocommerce-blocks/docs/designers/theming/README.md). We are unable to provide support for customizations under our [Support Policy](http://woocommerce.com/support-policy/). If you need to further customize a snippet, or extend its functionality, we highly recommend [Codeable](https://codeable.io/?ref=z4Hnp), or a [Certified WooExpert](https://woocommerce.com/experts/). diff --git a/plugins/woocommerce-blocks/docs/designers/theming/README.md b/plugins/woocommerce-blocks/docs/designers/theming/README.md index 38ec8261b5e..c6e225a59b8 100644 --- a/plugins/woocommerce-blocks/docs/designers/theming/README.md +++ b/plugins/woocommerce-blocks/docs/designers/theming/README.md @@ -1,18 +1,58 @@ # Theming -This page includes all documentation regarding WooCommerce Blocks and themes. +This page includes documentation about theming WooCommerce blocks and block themes. + +--- + +**Note:** this document assumes some previous knowledge about block theme development and some WordPress concepts. If you are completely new to block theme development, please check [Develop Your First Low-Code Block Theme](https://learn.wordpress.org/course/develop-your-first-low-code-block-theme/) +to learn about block theme development, and explore +the [Create Block Theme plugin](https://wordpress.org/plugins/create-block-theme/) tool when you're ready to create a +new theme. + +--- ## General concepts +### Block templates + +WooCommerce comes with several [block templates](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/templates/templates/blockified) by default. Those are: + +- Single Product (`single-product.html`) +- Product Catalog (`archive-product.html`) + - Products by Category (`taxonomy-product_cat.html`) + - Products by Tag (`taxonomy-product_tag.html`) + - Products by Attribute (`taxonomy-product_attribute.html`) +- Product Search Results (`product-search-results.html`) +- Page: Coming soon (`page-coming-soon.html`) +- Page: Cart (`page-cart.html`) +- Page: Checkout (`page-checkout.html`) +- Order Confirmation (`order-confirmation.html`) + +Block themes can customize those templates in the following ways: + +- It's possible to override the templates by creating a file with the same file name under the `/templates` folder. For example, if a block theme contains a `wp-content/themes/yourtheme/templates/single-product.html` template, it will take priority over the WooCommerce default Single Product template. +- Products by Category, Products by Tag and Products by Attribute templates fall back to the Product Catalog template. In other words, if a theme provides an `archive-product.html` template but doesn't provide a `taxonomy-product_cat.html` template, the Products by Category template will use the `archive-product.html` template. Same for the Products by Tag and Products by Attribute templates. +- It's possible to create templates for specific products and taxonomies. For example, if the theme provides a template with file name of `single-product-cap.html`, that template will be used when rendering the product with slug `cap`. Similarly, themes can provide specific taxonomy templates: `taxonomy-product_cat-clothing.html` would be used in the product category with slug `clothing`. +- Always keep in mind users can make modifications to the templates provided by the theme via the Site Editor. + +### Block template parts + +WooCommerce also comes with two specific [block template parts](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/templates/parts): + +- Mini-Cart (`mini-cart.html`): used inside the Mini-Cart block drawer. +- Checkout header (`checkout-header.html`): used as the header in the Checkout template. + +Similarly to the templates, they can be overriden by themes by adding a file with the same file name under the `/parts` folder. + ### Global styles WooCommerce blocks rely on [global styles](https://developer.wordpress.org/themes/global-settings-and-styles/styles/) for their styling. Global styles can be defined by themes via `theme.json` or by users via Appearance > Editor > Styles and offer several advantages over plain CSS: -* Better performance, as only the required CSS is printed into the page, reducing the bundle size to render a page. -* Can be easily customized by users via the UI. -* Gracefully handle conflicts between plugins and themes. -* Are not affected by markup or class name updates into individual blocks or components. -* Don't depend on a specific nesting order of blocks: users can freely move blocks around without styles breaking. +- Better performance, as only the required CSS is printed into the page, reducing the bundle size to render a page. +- Can be easily customized by users via the UI. +- Gracefully handle conflicts between plugins and themes. +- Are not affected by markup or class name updates into individual blocks or components. +- Don't depend on a specific nesting order of blocks: users can freely move blocks around without styles breaking. #### Example @@ -43,83 +83,9 @@ Before You can find more [documentation on global styles](https://developer.wordpress.org/themes/global-settings-and-styles/styles/) in developer.wordpress.org. You can also find the [list of WooCommerce blocks and their names in the docs](../../block-references/block-references.md). -### Block and component class names - -**Important: we strongly discourage writing CSS code based on existing block class names and prioritize using global styles when possible. We especially discourage writing CSS selectors that rely on a specific block being a descendant of another one, as users can move blocks around freely, so they are prone to breaking. Similar to WordPress itself, we consider the HTML structure within components, blocks, and block templates to be “private”, and subject to further change in the future, so using CSS to target the internals of a block or a block template is _not recommended or supported_.** - -WooCommerce Blocks follows BEM for class names, as [stated in our coding guidelines](../../contributors/coding-guidelines.md). All classes start with one of these two prefixes: - -* `.wc-block-`: class names specific to a single block. -* `.wc-block-components-`: class names specific to a component. The component might be reused by different blocks. - -The combination of block class names and component class names allows themes to style each component either globally or only in specific blocks. As an example, you could style all prices to be italics with: - -```css -/* This will apply to all block prices */ -.wc-block-components-formatted-money-amount { - font-style: italic; -} -``` - -But if you only wanted to make it italic in the Checkout block, that could be done adding the block selector: - -```css -/* This will apply to prices in the checkout block */ -.wc-block-checkout .wc-block-components-formatted-money-amount { - font-style: italic; -} -``` - -**Note:** for backwards compatibility, some components might have class names with both prefixes (ie: `wc-block-sort-select` and `wc-block-components-sort-select`). In those cases, the class name with `.wc-block-` prefix is deprecated and shouldn't be used in new code. It will be removed in future versions. If an element has both classes always style the one with `.wc-block-components-` prefix. - -### Container query class names - -Some of our components have responsive classes depending on the container width. The reason to use these classes instead of CSS media queries is to adapt to the container where the block is added (CSS media queries only allow reacting to viewport sizes). - -Those classes are: - -Container width | Class name -----------------|------------ -\>700px | `is-large` -521px-700px | `is-medium` -401px-520px | `is-small` -<=400px | `is-mobile` - -As an example, if we wanted to do the Checkout font size 10% larger when the container has a width of 521px or wider, we could do so with this code: - -```css -.wc-block-checkout.is-medium, -.wc-block-checkout.is-large { - font-size: 1.1em; -} -``` - -### WC Blocks _vs._ theme style conflicts for semantic elements - -WooCommerce Blocks uses HTML elements according to their semantic meaning, not their default layout. That means that some times blocks might use an anchor link (``) but display it as a button. Or the other way around, a `