woocommerce / woocommerce-blocks

(Deprecated) This plugin has been merged into woocommerce/woocommerce

📣 Announcement: New documentation location

The documentation for WooCommerce Blocks has moved to the WooCommerce monorepo.

Please refer to the documentation in the new location as the files in this repository will no longer be updated and the repository will be archived.

---

WooCommerce Blocks

This is the feature plugin for WooCommerce + the Gutenberg. This plugin serves as a space to iterate and explore new Blocks and updates to existing blocks for WooCommerce, and how WooCommerce might work with the block editor.

Use this plugin if you want access to the bleeding edge of available blocks for WooCommerce. However, stable blocks are bundled into WooCommerce, and can be added from the "WooCommerce" section in the block inserter.

• WCCOM product page
• User documentation

Table of Contents

• Documentation
  • Code Documentation
• Installing the plugin version
• Installing the development version
• Getting started with block development
• Long-term vision

Documentation

To find out more about the blocks and how to use them, check out the documentation on WooCommerce.com.

If you want to see what we're working on for future versions, or want to help out, read on.

Code Documentation

• Blocks - Documentation for specific Blocks.
• Editor Components - Shared components used in WooCommerce blocks for the editor (Gutenberg) UI.
• WooCommerce Blocks Handbook - Documentation for designers and developers on how to extend or contribute to blocks, and how internal developers should handle new releases.
• WooCommerce Blocks Storybook - Contains a list and demo of components used in the plugin.

Installing the plugin version

We release a new version of WooCommerce Blocks onto WordPress.org every few weeks, which can be used as an easier way to preview the features.

Note: The plugin follows a policy of supporting the "L0" strategy for version support. What this means is that the plugin will require the most recent version of WordPress. It will also require the most recent version of WooCommerce core at the time of a release. You can read more about this policy here.

1.Ensure you have the latest available versions of WordPress and WooCommerce installed on your site. 2. The plugin version is available on WordPress.org. Download the plugin version here. 3. Activate the plugin.

Installing the development version

1. Ensure you have the latest versions of WordPress and WooCommerce installed on your site.
2. Get a copy of this plugin using the green "Clone or download" button on the right.
3. Make sure you're using Node.js v16.15. If you use a Node version management tool such as nvm or n, you can do so by running nvm use or n auto, respectively.
4. npm install to install the dependencies.
5. composer install to install core dependencies.
6. To compile the code, run any of the following commands
   1. npm run build (production build).
   2. npm run dev (development build).
   3. npm start (development build + watching for changes).
7. Activate the plugin.

The source code is in the assets/ folder, and the compiled code is stored into build/.

Getting started with block development

Run through the "Writing Your First Block Type" tutorial for a quick course in block-building.

For deeper dive, try looking at the core blocks code, or see what components are available.

To begin contributing to the WooCommerce Blocks plugin, see our getting started guide and developer handbook.

Other useful docs to explore:

• InnerBlocks
• apiFetch
• @wordpress/editor
• @wordpress/create-block

Long-term vision

WooCommerce Blocks are the easiest, most flexible way to build your store's user interface and showcase your products.

woocommerce-blocks's Issues

Block options to choose order and limit product count

Store owners should be able to choose the order products are listed in a block. Like the shortcode, that could by popularity, newness etc.

A use case could be the I want a unique landing page for a category, rather than the default archive you get with core. On that page, I only want to show my 3 best selling products.

It should also be more clear how you could limit the amount of products which should be displayed.

UX: Changing display type

I'm curious why there are two different "screens"/user experiences for the same type of change:

1) Selecting the display mode the first time:

2) Changing the display mode after a product block has been configured:

---

I was thinking it could just go back to the first screen after clicking Display different products. That way the user is already familiar with the option choices and experience.

'undefined' class name on grid product blocks

The code that adds a class to the shortcode if the list layout is selected needs to be updated to prevent adding the 'undefined' class. Currently, all generated shortcodes are of the form [products limit="3" class="undefined" columns="3"].

Tag select

Add an option to the Edit Mode of the products block for searching and selecting products by tag. This is similar to the product category search and select feature we already have built out for the Products block, but for tags. We may want to make some sort of reusable component that we can use for all of these features.

This feature isn't in the current design for the block, but I'm leaving this open in case it gets added later or that was an oversight.

Individual product blocks pre-populated

If I create a new product block using the "Individual Products" block the same products are auto-selected if I choose to create another product block with "Individual Products".

I'm not sure if this is intentional or not. If it is, wouldn't the better option for the user be to Duplicate the block or convert it to a re-usable block?

Specific select: list reloads when adding/removing products

Sometimes when adding or removing products, the list of products that were selected refreshes, and for a split second, the pages jumps while the content is loading again.

Flow: I want customers to see a preview of specific products in a post / page

In this case the user might just want to funnel folks in to their product pages. The add to cart button would probably be replaced with a "Learn more" button / link. They may also like to display the short description.

Prototype: Todo
Sketch: Todo

Let's swap the category contents count / dropdown indicator

Sorry this was my bad from the Sketch design. But it looks weird when there's only one category with children in a long list.

Before

After

Flow: I've inserted some products but I don't want to display the add to cart buttons

Current prototype: todo

Sketch: todo

Individual products - remove rows slider

When displaying individual products we know the total number of products the user wants to display. So we only need to present a columns selector - rows should be automatically calculated.

When selecting a scope which requires no further input jump direct to preview

Currently, when you elect to display;

• Featured products
• On sale products
• All products

You're taken to a screen which confirms what you're displaying with the done button. The experience would be smoother if we just skipped that altogether and went directly to the preview.

Clicking "Add" in the search results dropdown should provide visual feedback that the product was added.

For now let's swap the text to "added" on click then fade-out the row and slide-up any rows beneath it. Keen to see how this tests cause it's feeling a little clunky now it's live.

Product types without options look a bit empty

Flow: I want customers to be able to add products with a specific attribute & term to their cart in a post/page

Current prototype: https://automattic.invisionapp.com/share/P4FL7W6VDT8#/screens/276308942_01e
Select Filter products > Attribute in scope selector.

Sketch: https://www.dropbox.com/s/dvp2x1poq1yukes/Add%20Products%20Block.sketch?dl=0

Flow: I want customers to be able to add on sale products to their cart in a post/page

Current prototype: todo

Sketch: https://www.dropbox.com/s/dvp2x1poq1yukes/Add%20Products%20Block.sketch?dl=0

Improve scalability of attribute and category selects.

The attribute and category select options will need testing and possible tweaking to make sure that they work OK on sites with hundreds or thousands of attributes or categories. Currently they pre-populate the list of attributes/categories with all of the attributes/categories when loaded, and this may not be scalable.

products do not display in 6-column format on backend....

Products do not display in 6-column format.

1-column, 2-column, 3-column, 4-column, and 5-column all work well.

• 6-column setting works on the front end.
• 6-column setting does NOT work on the back end - instead it works just like 1-column.

Add an active state for the scope switcher

Scope switcher: https://cloudup.com/cGBCQLlRaFN

Let's make it clear which scope is currently active when switching, and disable it as a selection.

Flow: I want customers to be able to add all my products to their cart in a post/page

Current prototype: https://automattic.invisionapp.com/share/P4FL7W6VDT8#/screens/276308942_01e
Select All products in scope selector.

Sketch: https://www.dropbox.com/s/dvp2x1poq1yukes/Add%20Products%20Block.sketch?dl=0

Sale/Featured/Top Rated/etc. options

We need the following possibilities added as options to the Products block (along with potentially other similar types of options):

• On Sale
• Featured
• Best Sellers
• Top Rated

I'm not sure the best way to implement these. They can be implemented as stand-alone options in the Edit Mode with no further customization or they can be implemented as a checkbox or something in the sidebar block options so they can be combined with options from the Edit Mode (e.g. Show products that are a specific attribute and on sale)

Modularization

I'm not sure at what point in the development process we should do this, but we need to modularize components where possible and export them so that third-party developers can extend and reuse WC components. See the Gutenberg blocks library for examples of how this should be done.

Flow: I want to change the products I've inserted entirely

Current prototype: https://automattic.invisionapp.com/share/P4FL7W6VDT8#/screens/276308935
Note the three different entry points;

• Pencil icon
• "Change" link in sidebar
• "Display different products" action button (inside ellipsis menu)

Sketch: https://www.dropbox.com/s/dvp2x1poq1yukes/Add%20Products%20Block.sketch?dl=0

Flow: I've inserted some products and want to update some of their titles / prices

Current prototype: todo

Sketch: todo

Flow: I want customers to be able to add my best selling products to their cart in a post/page

Current prototype: todo

Sketch: https://www.dropbox.com/s/dvp2x1poq1yukes/Add%20Products%20Block.sketch?dl=0

Remove list view

Just adding list-layout to the block output will require all themes to introduce new layout styles based just on that class.

Until a theme adds extra CSS to support this new class the frontend will not properly reflect what they are previewing in the block.

Storefront set to list view: https://cloudup.com/cCCN2gTKJDR

Close dropdowns when clicking off them

To stop fun stuff like this happening https://cloudup.com/cizdFS2n6h4

I think you mentioned this in the call yesterday but noting it here anyway.

Individual select product blocks broken when page is reloaded.

This seems to be something probably caused by the latest version of Gutenberg. If you create a block with individual select products and save, when you come back to the page you get errors on the block:

I don't know why the validation expects an empty string for include, but that is not correct. Weirdly this only happens for the product select and not the category one.

Center the Product Block Inserter in view on screen

When I go to add a product block there are times that I have to scroll up to see all the options on my screen.

I would expect that once I select to add a product block, the inserter options would be fully visible without me having to scroll up/down.

Here are two examples:

http://cld.wthms.co/GmZBH4

http://cld.wthms.co/UOZ1hI

"Center" might not be the right word. Maybe it's more "anchor at the top to make all options visible".

Flow: I want to change the layout of the products I've inserted

The user should be able to specify how many columns / rows products should be arranged in to.

Current prototype: todo

Sketch: todo

Individual Products Scope: "No products selected" message is obscured by scroll design detail

The fade is obscuring the text slightly.

Flow: I want customers to be able to add products from a specific category to their cart in a post/page

Current prototype: https://automattic.invisionapp.com/share/P4FL7W6VDT8#/screens/276308942_01e
Select Product category in scope selector.

Sketch: https://www.dropbox.com/s/dvp2x1poq1yukes/Add%20Products%20Block.sketch?dl=0

Flow: I want customers to be able to purchase a specific product directly from a post / page

In this flow we'll need to enable the user to change the add to cart button behaviour and label. They will likely want the button to read something like "Buy now" and redirect to the cart when clicked.

Prototype: Todo
Sketch: Todo

Flow: I want customers to be able to add specific products to their cart in a post/page

Current prototype: https://automattic.invisionapp.com/share/P4FL7W6VDT8#/screens/276308942_01e
Select Individual products in scope selector.

Sketch: https://www.dropbox.com/s/dvp2x1poq1yukes/Add%20Products%20Block.sketch?dl=0

Graceful error handling

The products block needs graceful error handling if columns gets set to 0 or the user inputs a crazy value for fields.

Final design

We need a public-facing final (or close-enough) design for the Products block. We can build the functionality without this, but it's necessary for polish and getting public feedback.

Flow: I want customers to be able to add my best rated products to their cart in a post/page

Current prototype: todo

Sketch: https://www.dropbox.com/s/dvp2x1poq1yukes/Add%20Products%20Block.sketch?dl=0

Spacing between rows

Just need a little spacing between product rows; https://cloudup.com/cWqORu3eRqT

Search and select products by attribute

Add an option to the Edit Mode of the products block for searching and selecting products by attribute. This is similar to the product category search and select feature we already have built out for the Products block, but for attributes. We may want to make some sort of reusable component that we can use for all of these features.

Category shortcode argument might be incorrect?

categories vs category

Running master of WC core:

This shortcode is generated by Gutenberg, and doesn't output any products:

[products limit="3" columns="3" category="30,29,28,27"]

This shortcode works:
[products limit="3" columns="3" categories="30,29,28,27"]

Haven't really dug in much, but it's pretty strange since WC core is expecting category as far as I can tell.

Hide the grid/list toggle when in edit mode

In this state it doesn't do anything so it probably makes most sense to hide it.

CSS styling

The CSS styles need to be polished and finalized. This does not need to be completed until a final design is approved. Rough styles work until then.

Add a `from` transform to each block to support legacy shortcodes

If a page has the products shortcode already on it (from posts created using the classic editor) convert the shortcode into a pre-populated Products block. More investigating will need to be done to see if this is possible, but I believe Gutenberg 2.1 has some shortcode handling features so it should be possible.

Possible use case for transformations API: WordPress/gutenberg#4578

It shouldn't be possible to finish adding the block if no products are selected.

For example if you elect to display individual products but do not select any, then click done you see this;

I appreciate that's what you'd see on the frontend but nobody would ever want to use the product block this way.

The "Done" button should be disabled (with cursor: not-allowed;) in this case with a tooltip which states "Please search for and select products to display first".

Switching to List View Should Keep Original Number of Products Visible

If you have a Grid View set to show 1 row with 4 columns and you switch to List View the number of rows is set to 1 which hides products. I think when switching the rows should be set to $rows * columns.

4 Columns x 2 Rows = 8 Rows
3 Columns x 3 Rows = 9 Rows

etc...

It's confusing switching to List View and having products disappear. Originally noted in #59

Flow: I want the products I've inserted to be paginated

Current prototype: todo

Sketch: todo

Design quirks in category list

• List width doesn't match the search input; https://cloudup.com/cOACJ-sSwjX
• Let's align the chevrons; https://cloudup.com/cCoqqy7BDVu
• The scrollbar is in a strange place; https://cloudup.com/cna-oucsCOZ
• The entire row presents the pointer cursor on hover, but nothing happens unless you specifically click the checkbox. Let's make the entire row toggle the checkbox.

Flow: I want customers to be able to add my featured products to their cart in a post/page

Current prototype: todo

Sketch: https://www.dropbox.com/s/dvp2x1poq1yukes/Add%20Products%20Block.sketch?dl=0

Grid view should be default

On current master after you insert a product block neither grid or list view are selected. Let's make grid the default.

Filter by attribute display double loading text

Add max-height to individual product search results

With lots of products the results list could become awkward to use;

Let's apply a sensible max-height with overflow: auto;.