RFC: Product Collection vs Synced Patterns and Template Parts

[kmanijak]

This RFC touches on the conflict between the contextual nature of the blocks (example of Product Collection in contextless places like Synced Patterns and Template Parts. We don’t have a good answer on how to proceed with that conflict and if the features/requirements we came up with for Product Collection are feasible long-term.

Problem – in short

Some blocks, especially Product Collection and its Collections generate content that is only meaningful in association with an object:

• a product (e.g. price, or upsells)
• an order
• a cart
• a taxonomy
• others, for example, a session (e.g. Recently Viewed Products).

Some collections/blocks may behave differently in different contexts (e.g. product vs cart upsells) and/or may expose different/additional capabilities/options to the user (e.g. contextual filters, such as “current category”, and/or other options).

Context influences what can be previewed in Editor. From a preview perspective, context can be partially or fully resolved in the Editor. For example:

We know that we’re Editing in the “product” context when we’re editing the Single Product template.
If we’re editing the Single Product template of a specific product, we also know its ID.
In the latter case, we can render content that more closely resembles what shoppers will see in the frontend. We anticipate that this will become more and more important as we work to enable more store customization capabilities at the product level — for example, knowing a context fully could enable us to render additional Add To Cart Form inner blocks, to enable users to customize the presentation of individual product features, such as variations, add-ons, bundled products, etc.

In many cases, and for blocks that require a primary working context, we want to allow the user to provide it manually. For example, a user may want to put together a Product Comparison Table on a landing page, complete with Price and Add To Cart button blocks. Because the products associated with these blocks cannot be known in the context of a WP page or post, we want to guide users to manually do the association.

Based on the above, we have identified 5 contexts that we want to formally define (and may later extend): Site (generic), Product, Archive, Cart, and Order.

Our ability to detect “Woo context” in the Editor fails when a block is inserted in a Template Part or Synced Pattern.

We could fall back to “Site” context, however, the user may intend to utilize that Template Part or Pattern in a location where context might reveal additional capabilities:

• What should happen when a Woo block is inserted in a new Template Part or Synced Pattern, where context is literally “unknown”? Should the user manually supply the intended working context?
• What if a preconfigured block is transformed into a Template Part or Synced Pattern and is used in a context where its settings don’t make sense?

Problem – long version

What is Product Collection block and collections?

In terms of functionality, Product Collection is a block similar to Query Loop. Query Loop displays a list of posts, while Product Collection displays a list of products. One of the key differences is the Product Collection is multipurpose.

We introduced a concept of “collections” to address different merchants’ needs. For instance, there are “On Sale” or “New Arrivals” collections. Collections have the same UI representation but their query attributes differ. For example:

• “On Sale” has:
  • onSale flag set to true,
  • alphabetical order by default.
• “New Arrivals” has:
  • onSale flag set to false by default,
  • newest to oldest order.

So far, so good.

Contextual collections

Choosing context manually

We plan more complex collections that generate different results depending on the context, for instance, “Upsells” or “Cross-Sells”. These collections need to know product context. This is not a new problem – often this is solved by prompting merchants to choose the product like in Reviews by Product block:

Detecting context automatically

We want to make Product Collection smarter than that and detect the context automatically based on location in the Editor and only if unavailable, prompt the user to choose one. Here’s the flow on the diagram with the Upsells as an example:

And here’s the link to the full diagram.

The above use case was just an example, but there’s more:

• Some collections may not be available at all in some contexts, like Viewed but not Bought which is added by the Product Recommendations plugin. It’ll be visible in the order context but hidden in others.

• The same collection, like Featured, may behave in three different ways depending on the template it’s added to:
  • In an archive and product templates, it’ll be inserted with the Category, Attribute, or Tag filter automatically added and set to Same as currently viewed to use the available context.
  • In other contexts, like a custom landing page, it won’t have any pre-added filters and the user will be able to define them as they see fit.

These are the context/location types we defined (that list may be extended in the future):

• Site – generic, default.
• Product – single product template or block.
• Order – order confirmation template.
• Cart – cart/checkout templates or cart/checkout/mini-cart blocks.
• Archive – an archive page related to WC, such as the product_cat or product_tag taxonomies.

We implemented the context/location recognition in this PR: #43997.

The problem: context in Template Parts or Synced Patterns.

All the contextual mechanisms fail when we combine Product Collection with Template Parts or Synced Patterns.

1. 🔴 When inserting Product Collection in Template Parts or Synced Patterns we cannot determine the context hence:
   • We cannot show/hide collections contextually (e.g. Viewed but not Bought that should be available only in Order context).
   • We cannot set the automatic context (e.g. “From current product”). This option could potentially fall back to a more generic one as “From current context”.
   • Contextual filters lose their meaning (e.g. “Category IS same as currently viewed”). This could be potentially applied conditionally but that increases complexity.
2. 🔴 We lose the context when the already configured Product Collection is moved to the Template Part or Synced Pattern :
   • Collection can be used in any context wherever Template Part or Synced Pattern is used even if they don’t make sense there.
   • We cannot determine that the collection configured to get context automatically e.g. “From current product” will have such context. Once again, that could be solved by falling back to a more generic option but it changes the collection behavior.
   • Contextual filters, when configured, lose their sense as we cannot determine what context the collection will be used in.

Request for Comments, Questions, and Concerns

These are examples based on designs we have but obviously there’s bigger potential in the contextual nature of blocks. However, we should not continue exploring them until we answer the key questions:

• Is there a way for contextual features and contextless areas in Editor to co-exist?
  • If so, we’re open to suggestions.
  • If not, does it mean these features we came up with cannot be implemented or should be simplified (more generic)? In that case, should WooCommerce stop pursuing the path of making blocks smarter based on context because of these technical limitations?

Thank you!

[manospsyx]

Hey @kmanijak -- here's my understanding of the problem:

• The same instance of a context-aware block might be edited in a context-less area (template part, pattern), or in a context-ful area (template, page, post). Obviously, the capabilities that the block exposes shouldn't change depending on where it's being edited.
• When a (new) context-enabled block is added to a context-ful location -- like a template or page -- it's possible to infer the context and expose the right capabilities. In some cases, context is manually provided (e.g. Upsells block added to a "Site" location -- user needs to indicate the product).
• This "detection" of context is not possible when a new block is added to a context-less area -- a template part or a pattern.

Some additional observations:

• It appears that users can edit template part contents in any location where the template part is edited.
• I don't observe the same with synced patterns. I find that a little unexpected.

Some ideas that may point to a solution:

• If "details about the context" are persisted to the block (attributes) after it has been added in a "context-ful" location, then those attributes could continue to provide knowledge of context if the block is later wrapped in a template part or synced pattern. If a user decides to edit the template part or synced pattern, the block will need to communicate that it was meant for use in, say, product templates -- a label perhaps?
• Things get more interesting if the block is created in a template part or (synced) pattern. What is the intended use?
  • For blocks designed to work in a single context other than "Site", what if assumed that the user's intention is to eventually utilize the template part in its primary context? In this case, we could expose all associated block options based on this assumption. e.g. the "Viewed But Not Purchased" or "Frequently Bought Together" collections could expose their full feature set without complaining, because they are only meant to be used in one context.
  • This would be impossible for blocks designed to work differently in multiple contexts, or blocks that vary their behavior depending on context -- like the Upsells block, which varies its behavior in Product vs Cart context. I've wanted to avoid this complexity as it tends to lead to problems like this. So what if, instead of having just one Upsells variation, we had multiple ones -- Upsells, Cart Upsells, and Order Upsells? Would that solve the problem?

[imanish003]

If someone saves Upsells as a pattern and adds it to an archive page, we'd reset it to Custom and inform the user.

In case of Sync Patterns, I don't think it's possible to change the collection itself. AFAIK Sync patterns are saved as post in DB. So if we change Sync pattern at one place, it will be changed at all other places too. Therefore, If we change the collection, then it will reflect at all other places too.

@kmanijak Can you please confirm if my understanding is correct? 🙂

[jarekmorawski]

Huh. Can we add anything to the synced pattern block/element's Inspector or toolbar?

[kmanijak]

In case of Sync Patterns, I don't think it's possible to change the collection itself. AFAIK Sync patterns are saved as post in DB. So if we change Sync pattern at one place, it will be changed at all other places too. Therefore, If we change the collection, then it will reflect at all other places too.
@kmanijak Can you please confirm if my understanding is correct? 🙂

That's how I understand it too. So basically all of the latest edits are propagated to all instances of synced pattern. So.. actually the fallback could be implemented on the front end during rendering.

Huh. Can we add anything to the synced pattern block/element's Inspector or toolbar?

@jarekmorawski , you mean recognising if Product Collection is within synced pattern and if so, modifying inspector controls?

[imanish003]

Can we add anything to the synced pattern block/element's Inspector or toolbar?

@jarekmorawski AFAIK Yes, we can add anything to Inspector or Toolbar, if we don't modify any attribute OR structure of block. In other words, We can use values of attributes to dynamically add anything to Inspector or Toolbar.

[imanish003]

So.. actually the fallback could be implemented on the front end during rendering.

@kmanijak Yeah, But we also wanna communicate it in Editor. I guess, for this, we can add a Notice to inspector control or Main content, without changing any attribute value.

[nerrad]

What scenarios would have people use Product Collections in a synced pattern?
What scenarios would have people use it in a template part?

Is it feasible to not enable usage in synced patterns or template parts for now while figuring out the UX issues for those cases?

[jarekmorawski]

What scenarios would have people use Product Collections in a synced pattern?

Almost any collection type, like bestsellers or top-rated products. As a theme builder or savvy merchant, I can imagine myself wanting to save such sections as patterns to keep the store visually consistent across different pages.

What scenarios would have people use it in a template part?

Bestsellers in the footer?

Is it feasible to not enable usage in synced patterns or template parts for now while figuring out the UX issues for those cases?

I'd be okay with this. The simplest solution is to hide the Create pattern option from the parent group's contextual menu and hide Product Collection from the inserter when the user edits a synced pattern or a template part.

[manospsyx]

A couple scenarios where creating a synced pattern would make sense:

• In archive templates (e.g. Products by Category), the Product Collection could be embedded in a synced pattern to ensure that when/if merchants create templates for specific categories, then styling/layout changes made in one category will be inherited by all. By default, this is how I would recommend shipping the template.
• The same is true for Upsells and Related Product collections. By having those wrapped in a synced pattern, any changes made to the "universal" Product Page template would be inherited by all templates created for individual products (e.g. styling changes, or exclusions of certain products/results from single product up-sells store-wide).

[nerrad]

Some other thoughts/questions.

I'm wary of coupling context/area to saved patterns. I'm thinking of the scenario where there are layouts that have to be duplicated for all the different contexts/areas that the pattern might be used in. Rather than always coupling context have we considered:

• For synced patterns and/or template parts, there is usually meaningful intent behind not only the layout, but also the content that is displayed. In those cases, I think these should always retain the details for the content (whether that be a query, selected block, recommendation engine etc) and that should be at the block level.
• All blocks should have fallbacks for handling when context is not available so that they can be utilized in non-synced patterns. LIkely this means that context/area is not persisted for those patterns and is assumed depending on where they are inserted. Pattern previews and editing the pattern would utilize the fallbacks (as a part of the sample product algorithm).
• At some point, we'll need to consider the behaviour of synced pattern overrides and how that applies to this problem space.

[jarekmorawski]

100% agree!

[manospsyx]

I love the ongoing dialogue and appreciate the those of you flashing the warning lights of "overengineering" :)

It sounds like some of us don't like the idea of formalizing context at the Pattern level -- the voices worrying that we might be engineering something major here just to address something minor must be heard.

I'm wary of coupling context/area to saved patterns.

At the block level, we want to expose additional (contextual) capabilities in a way that feels intuitive to the user and requires no additional decisions to be made, and therefore:

• I agree that requiring the user to understand our foundation of "context" (no matter where) is against the simplicity that we want to aim for.
• I see some risk in formalizing "store context" at the UI/UX level, at a point that we still haven't formalized this concept at the API level.

How do you feel about implementing a fallback mechanism on a case-by-case basis, based on contextual features? One Analogy could be HTML. Most of the time, even if developers write wrong HTML, there are always fallback mechanisms, and the webpage still works. We can try implementing something similar to HTML for cases where we can.

Not sure yet. I prefer to keep things simple at all costs though :) As I said, I don't want us to be solving problems that the user doesn't have or doesn't care about.

Here's something we have to decide first. Consider the following Scenario:

1. User adds a Product Collection to a Woo template, then goes on to utilize contextual capabilities (e.g. "current taxonomy" filters).
2. User creates a non-synced Pattern that contains that block -- from within the template.
3. User navigates to Patterns, and decides to edit the Pattern they created directly, outside its original creation context.

In this scenario, should the user see any of the contextual capabilities that they enabled on the Product Collection block ("current taxonomy" filters) while editing the Pattern, or not?

If your answer here is "yes", remember that this is what creates the need to introduce constraints/guardrails around the use of this Pattern relative to context.

Thinking about this myself, I would say "no", because:

1. I am strongly attracted by the simplicity of this.
2. Patterns are meant to be context-agnostic by design, and I don't want us to go against something so basic.

For non-synced patterns, it's easy for me to imagine that they have to expose only context-less features (=render assuming "Site" context) when the Pattern is edited. The "context-sensitive" configuration will be provided by (and exposed to) the user depending on where they utilize the Pattern. So far so good.

As @nerrad said:

LIkely this means that context/area is not persisted for those patterns and is assumed depending on where they are inserted. Pattern previews and editing the pattern would utilize the fallbacks (as a part of the sample product algorithm).

---

Now consider this:

1. User adds a Product Collection to a Woo template, then goes on to utilize contextual capabilities (e.g. "current taxonomy" filters).
2. User creates a synced Pattern that contains that block -- from within the template.
3. User navigates to Patterns, and decides to edit the Pattern they created directly, outside its original creation context. My understanding is that the user is no longer to edit the Pattern in the template where it was created in step (2).

In this scenario, I believe that contextual capabilities should be:

• persisted with the Pattern, and also
• preserved / rendered when the Pattern is edited.

What should users experience when they insert the Pattern in any context?

• Contextual capabilities will be preserved, if they were saved in the Pattern in the first place.
• Any contextual capabilities will be ignored if the "target" context does not match the "source" context persisted at the block (not pattern!) level.

And what will users experience when they create a synced Pattern from scratch?

I think that a good simplification (and way forward) here would be to disable all contextual capabilities in this environment/scenario (= assume "Site" context only).

Thoughts?

[xristos3490]

I like the simplicity of your proposal, Manos, and it surely helps us land a decision!

One thing that interests me about this proposal is the need to keep the origin context (the one at the time of insertion) at the block level. I like this idea because it solves most of our problems here, giving us complete control of the block settings. It's basically the hidden "Store Area" setting that Manish described, but defaulting to the insertion context (an assumption of intent we are making to simplify things).

I have a few concerns/questions.

Any contextual capabilities will be ignored

Regarding the resetting process, instead of using a case-by-case process to identify and reset features, we could take a more deterministic approach by resetting the query to its default value. This should simplify the process and prevent the block from getting into an "unpredictable" state(?). We can always preserve appearance and display settings, though!

At this point, I think we agree that handling a simple block in the wrong context would be to:

• Reset features and show an informational notice, or,
• Prompt for a context to be selected on the spot (if the selected variation allows it.)

For non-synced patterns, it's easy for me to imagine that they have to expose only context-less features

Interesting. How about exposing them in all cases, including simple patterns? I feel like this difference here would make things more complex since these areas already have their unique features in place.

So, when editing from within patterns (synced or not) and template parts, we always respect the origin context; if it's not "site," we utilize the preview mode.

Editing outside the Patterns-Parts areas, like within a template or a post:

• Adding a pattern(not synced) containing a PC block will immediately flatten itself into blocks, so we follow the same rules for a simple block.
• Adding a template part or a synced pattern that contains a PC block then:
  • If contexts match (block's origin = current), everything is good.
  • If they don't match, we warn the user with some notice at the block level. Since template parts allow inline editing, completely disabling the inspector controls would be an option, or allowing only appearance and display settings to be modified. In this case, it would also be best to avoid rendering anything on the front end (just like one would expect when adding a ProductTitle block on their homepage, for example). This case needs design, though.

What do you all think?

[xristos3490]

Also, just to clarify:

It's basically the hidden "Store Area" setting that Manish described, but defaulting to the insertion context (an assumption of intent we are making to simplify things).

I'm not saying that hiding this setting is good for UI simplicity only. Having a setting like this (even if it's hidden) would establish a 1-1 connection of a PC block with a single context, which is something I think we need to avoid at this point.

[jarekmorawski]

Having a setting like this (even if it's hidden) would establish a 1-1 connection of a PC block with a single context, which is something I think we need to avoid at this point.

Agreed!

Regarding the resetting process, instead of using a case-by-case process to identify and reset features, we could take a more deterministic approach by resetting the query to its default value.

Sounds good. Would Site be the default context? If so, I'm grand.

So, when editing from within patterns (synced or not) and template parts, we always respect the origin context; if it's not "site," we utilize the preview mode.

Do you mean that we'd put the block in Preview mode when it's inserted in a non-supported context? That could be confusing because the Preview label exists to inform the user when the content will be displayed dynamically... but in this case, it'll never be displayed, which means the block will not show up on the front-end until the user detaches the pattern and modifies its settings.

I wonder if something like this could work?

We'd display the notice within the block, which isn't perfect UX, but it sure draws attention to the error. Clicking Detach would detach the synced pattern and reset the block to the default state. We'd also disable all settings in the Inspector and repeat the notice there, too.

When the user clicks Detach & edit, we detach the pattern and restore the block to the detected context (for instance, if the synced pattern was set up for Best Sellers and dropped in a checkout template, we change it to Upsells) or, if we can't detect context with 100% certainty, to the default.

[xristos3490]

Love the idea of handling this with a "Detach & Edit" CTA, @jarekmorawski! I'll refer to this state as "recovery mode" which will have three states in my mind:

1. The one you shared; which handles the placement within template parts prompting the user to detach them.
2. A similar one for synced patterns that don't allow inline editing, and;
3. The case where a single PC block is added; a simpler one prompting like "Reset & Edit".

Do you mean that we'd put the block in Preview mode when it's inserted in a non-supported context?

The way I see it, there are three states:

1. Contexts matched
2. Preview mode - missing full context or being in isolated areas such as patterns (synced or not), and template parts.
3. Recovery mode - handling wrong placement of PC blocks (e.g., pasted ones)/inline editing of template parts/previewing synced patterns.

So basically, the idea is to only use the preview mode when full context is missing or within isolated areas.

Thoughts? 🤔

When the user clicks Detach & edit, we detach the pattern and restore the block to the detected context (for instance, if the synced pattern was set up for Best Sellers and dropped in a checkout template, we change it to Upsells) or, if we can't detect context with 100% certainty, to the default.

I'm a bit skeptical about how predictable this system can be. That's why I'm also in favor of resetting the query instead of trying to find the best alternative. For example, I would imagine that after a "Detach/Reset & Edit" click, we could utilize the collection chooser.

Sounds good. Would Site be the default context?

Yup! But this also means that creating context-based PC blocks can only be done within the relevant areas.

I believe it's a good tradeoff, considering we can't provide a UI for this. However, I can imagine how frustrating it would be to accidentally remove a context-based PC block from a pattern and have to add it back in somehow. The only option would be to create it somewhere relevant and then paste it in.

[jarekmorawski]

Preview mode

I'd argue that we shouldn't use the Preview mode at all in this case because it isn't actionable. If someone adds a synced pattern containing a PC block with an unsupported setup, we should default to the "recovery" mode.

That's why I'm also in favor of resetting the query instead of trying to find the best alternative. For example, I would imagine that after a "Detach/Reset & Edit" click, we could utilize the collection chooser.

I'd be fine with it if that means more clarity and simpler, less error-prone implementation.

Yup! But this also means that creating context-based PC blocks can only be done within the relevant areas.

That's probably how most people will approach it anyway.

The only option would be to create it somewhere relevant and then paste it in.

That's a valid concern and honestly, I don't have a good answer. It sounds like a niche use case and we can deal with it if it becomes common. If the user does it by mistake without saving changes, they can use the editor's undo function.