Partially synced patterns

[talldan]

Related: #48458

The concept of partial syncing of patterns has been discussed in #48458. There's a good idea of the goal, but a challenge has been developing a mental model for how this might work technically. I think it's worth writing down ideas for how it might work, and hopefully this will allow all contributors to discuss and develop the idea, and have some alignment.

The thoughts here are mostly developed from conversations with various contributors across github issues, prs and other discussions. This is an attempt to piece it all together.

The Goal

Today, when you insert a pattern, the blocks from that pattern are completely decoupled and standalone. There's no way to tell that those blocks originated from a pattern, especially since they can be edited to no longer resemble the source pattern.

Partially synced mode is different. When a pattern that's partially synced is inserted, it retains a reference to the source pattern. The blocks within the pattern are locked so that they cannot be removed or reordered and new blocks cannot be inserted (this is called contentOnly locking). Only specific parts of the pattern considered 'content' can be edited (denoted by adding __experimentalRole: 'content' to a block's definition).

When the source pattern is updated, all instances of blocks that reference the source pattern are updated too (much like a reusable block), but the content values the user entered are retained. The best way to think of this is that the user can update the design of a pattern, but doesn't lose content that exists in templates and posts.

Similar concepts

The concept of partial syncing could be considered as similar to the way a handlebars, mustache, or other templating system works.

In templating systems, an important part is that data is kept separate from the template markup. A developer can update the markup to something very different, but the data can still be interpolated into the template to produce resulting HTML. The same data can even be applied to different templates.

For partially synced patterns, I think it's also important that the data (the values of 'content' attributes) is kept separate from the template (the source pattern). This way, the data can be interpolated or injected into the pattern to produce the resulting HTML.

An implementation

Source pattern

Usually, a templating system includes tokens that indicate which parts can be replaced. e.g. <h2>{{ callToAction.title }}</h2>.

For blocks, this could be achieved using a data attribute.

<!-- wp:heading -->
<h2 data-wp-pattern-html="heading.content">Get in touch</h2>
<!-- /wp:heading -->

The html part of the attribute name (data-wp-pattern-html) implies that the inner html of the tag can be replaced by a pattern block's heading.content data.

This way, the pattern is still valid HTML and can contain fallback values.

Pattern blocks

So far, there have been explorations for making both the pattern and reusable block the one that has the partially synced mode. For this issue, I'll use the pattern block as the example, but it's arbitrary, and it could work the same way on either block.

A partially synced pattern block could exist in a user's content in the following way:

<!-- wp:pattern { 
    "syncStatus":"partial",
    "slug": "call-to-action",
    "content": { "heading.content": "My title" }
} /-->

The attributes are:

• syncStatus - fairly self explanatory, but it determines whether partial syncing is active
• slug - the reference to the source pattern, in the future this may reference a wp_block post type
• content - the data that we want to replace in the pattern when it renders.

The other thing to note is that the block is dynamic and runs the interpolation process when rendering.

Rendering a pattern instance

When the pattern is rendered the data attributes are used to replace the data in the user's pattern.

The source pattern:

<!-- wp:heading -->
<h2 data-wp-pattern-html="heading.content">Get in touch</h2>
<!-- /wp:heading -->

Is updated with the block's content data:

{ "heading.content": "My title" }

To produce the desired html:

<h2>My title</h2>

Challenges

A big challenge is that when a user updates the design of the source pattern, they may do so in a way that makes it difficult to reconcile the pattern instance's content data and the source pattern's data attributes. They might reorder, remove blocks or add multiple blocks of the same type. An area for exploration will be ensuring the keys used in both places remain as correct as possible when the source pattern is modified.

One positive is that if the user is updating a wp_block post type that's considered a pattern, it should be possible to detect where problems may occur by comparing the content attributes of the previous revision with those of the version the user is trying to save. It might be possible to offer tools for resolving issues if the UX can be made simple enough.

I also don't have a clear idea of what the UX will be when a user updates the design of a pattern, I think this needs some design work.

Next steps

Let's discuss. Does this solve the problem? Any alternative ideas?

In terms of the implementation, I think the best option is to start by developing around the simplest possible use case. A very simple pattern that can be updated and only has a few content attributes. From that initial implementation it should be possible to start considering more advanced use cases.

cc @WordPress/gutenberg-core, @aaronrobertshaw, @glendaviesnz, @kevin940726

[SaxonF]

Exciting! First question I'd ask if whether we'd need to distinguish between partial and full syncing? Could we instead make use of the already familiar locking experience? e.g. a pattern is either synced or not, if it is, you can lock certain blocks that you don't want to be editable.

[youknowriad]

I think the concept of "contentOnly" locking and "partial syncing" are different (one could be just an implementation detail of the other) because contentOnly locking is about editing blocks, the blocks are still saved entirely and can even be edited if you go to the code view. For partial syncing, it's different, the rendering needs to "mix" a source pattern with a partially saved pattern.

[talldan]

@SaxonF Would you still have a form of partial syncing?

Just to run through a use case:

• User A makes a CTA pattern, but locks the heading so that it can't be edited.
• User B inserts this in a post and changes the button label.
• User A updates the original pattern changing both the heading and the button label.

When syncing, does the inserted pattern have both an updated heading and button? Or does only the heading change with user B's content staying the same?

I'm guessing the second option, am I right? 😄

[gziolo]

When syncing, does the inserted pattern have both an updated heading and button? Or does only the heading change with user B's content staying the same?

I'm guessing the second option, am I right? 😄

My understanding is that it's the second option. The button label changed by user B is stored in a separate layer that every time gets dynamically applied to the source pattern that user A controls.

One positive is that if the user is updating a wp_block that's considered a pattern, it should be possible to detect where problems may occur by comparing the content attributes of the previous revision with those of the version the user is trying to save. It might be possible to offer tools for resolving issues if the UX can be made simple enough.

It's valid only when you use wp_block as the source for the pattern that you combine with the content provided by the user. The important distinction here should be noted for the patterns used as the design source from Pattern Directory, registered by the block theme, the plugin, or the site's owner. In all those cases, you won't have access to their previous revisions.

[youknowriad]

It seems the ideal solution is to actually "mix" the source with the saved pattern on the server. The problem is that we don't have "full parsing" in the server just yet. Meaning we can't extract and update the blocks in the server sing the format you proposed above.

So:

• we either have to solve PHP parsing of blocks: HTML parsing seems solvable but the fact that server side registration of blocks is not mandatory seem like a big blocker.
• find an alternative way to save the reference patterns/blocks (placeholder content/attributes) and use regex to replace these. Requires changing how we save wp_block CPT. Maybe each saved wp_block need to be saved using the real content and the fake placeholders. Also raises the question about whether the content can impact the structure in some cases.
• Accept that "partially synced" means synced with the reference pattern only when loaded in the editor: It feels like this options removes a lot of value from the "partially synced" proposal. So probably to be discarded.

[talldan]

It seems the ideal solution is to actually "mix" the source with the saved pattern on the server.

Yeah, I'm not sure how else it could work that would achieve the 'update everywhere' feature.

Good point about not being able to serialize on the server, completely missed that 🤔

Requires changing how we save wp_block CPT. Maybe each saved wp_block need to be saved using the real content and the fake placeholders. Also raises the question about whether the content can impact the structure in some cases.

So when a pattern is created, placeholder values can be injected (e.g. {{ wp-button.title }}), and possibly we could also store some default values in meta { "wp-button.title": "Sign up!" }, then interpolation would achieved like an actual template engine.

Seems like it would work, though it's a shame it requires creating something largely new, rather than using the existing block data.

[youknowriad]

We're once again suffering from the fact that we use two languages to deal with blocks "php" and "js" and somethings are possible in one but not the other. Gutenberg would have been so much simpler and better if it was all JS :)

For now, I guess the only option left is the second one. so yeah save "placeholders". And good call about the default values in meta to serve in the case of "full sync". That way we don't duplicate the content in the database to allow the pattern/block to be used both in partial and full sync.

[mtias]

We might not need to save placeholders if we can pair the act of "naming" a block (add a key) with the addition of a data-attr marker for sourced content attributes so that the tag processor con identify the entire element to be replaced. Mind we shouldn't need inline token placeholder if we replace an entire element. That was part of the discussion with @gziolo and @dmsnell a little while back around this problem space.

[gziolo]

It seems the ideal solution is to actually "mix" the source with the saved pattern on the server. The problem is that we don't have "full parsing" in the server just yet. Meaning we can't extract and update the blocks in the server sing the format you proposed above.

Yes, it's an extremely important point to keep in mind. There is an ongoing exploration to source block attributes from saved HTML also on the server that @dmsnell started in #46345. However, it might never be possible to have a fully reliable system to source those attributes from saved HTML in case blocks change over time the internal HTML structure and the shape of block attribute definitions as outlined in #49437. There are multiple examples of core blocks like Gallery, Quote, List that switched from single blocks to inner blocks which over time makes it nearly impossible to correctly source attributes for those blocks on the server in the format they used before transitioning to inner blocks. It's totally doable in the block editor thanks to the deprecations system but it's working only with JavaScript.

So when a pattern is created, placeholder values can be injected (e.g. {{ wp-button.title }}), and possibly we could also store some default values in meta { "wp-button.title": "Sign up!" }, then interpolation would achieved like an actual template engine.

Using placeholders has been another exploration that @dmsnell has been championing for quite some time and it's documented in detail at #39831.

For now, I guess the only option left is the second one. so yeah save "placeholders". And good call about the default values in meta to serve in the case of "full sync". That way we don't duplicate the content in the database to allow the pattern/block to be used both in partial and full sync.

Yes, I agree with the sentiment that having a system where you can mark places where the user injects the content, but keeping the default values would be the best approach. I think you greatly captured all the benefits it brings, given all the flexibility with this approach.

[gziolo]

We might not need to save placeholders if we can pair the act of "naming" a block (add a key) with the addition of a data-attr marker for sourced content attributes so that the tag processor can identify the entire element to be replaced. Mind we shouldn't need inline token placeholder if we replace an entire element.

It's one of the approaches I have discussed with a few contributors. This particular conversation was inspired by the ideas developed for the Interactivity API project (full proposal) – namely the server-side rendering for directives WordPress/block-interactivity-experiments#120. The idea here is to use HTML data attributes to mark the content in the source of the pattern so we can use that information to walk over HTML and replace the content with the processor built on top of the HTML Tag Processor introduced in WordPress 6.2.

Let's assume that we use a very similar format (changed only to make the illustration easier to follow) to what @talldan presented in the description for the partially synced pattern:

<!-- wp:pattern { 
    "syncStatus":"partial",
    "slug": "simple-call-to-action",
    "content": {
        "heading': {
            "content": "<em>My heading text</em>"
        },
        "paragraph": {
            "content": "<em>My paragraph text</em>"
        }
    }
} /-->

I assumed that we have a way to name the block with a unique key so we could identify precisely where to look for block attributes with the role content. This way, every block of the same type can have a different name, e.g. heading and paragrapah. In practice, it would be more like reviewTitle or actionButtonText.

Now let's take the pattern simple-call-to-action from Pattern Directory and annotate it with data-wp-pattern-html data attributes:

<!-- wp:group {"align":"full","style":{"color":{"text":"#000000","background":"#ffffff"}}} -->
<div class="wp-block-group alignfull has-text-color has-background" style="background-color:#ffffff;color:#000000">
	<!-- wp:spacer {"height":64} -->
	<div style="height:64px" aria-hidden="true" class="wp-block-spacer"></div>
	<!-- /wp:spacer -->
	<!-- wp:paragraph {"align":"center","style":{"typography":{"lineHeight":".9"}},"fontSize":"small"} -->
	<p data-wp-pattern-html="content.paragraph.content" class="has-text-align-center has-small-font-size" style="line-height:.9"><strong>GET IN TOUCH</strong></p>
		<!-- /wp:paragraph -->
	<!-- wp:heading {"textAlign":"center","style":{"typography":{"fontSize":59,"lineHeight":"1.15"}}} -->
	<h2 data-wp-pattern-html="content.heading.content" class="has-text-align-center" id="schedule-a-visit" style="font-size:59px;line-height:1.15"><strong>Schedule a Visit</strong></h2>
	<!-- /wp:heading -->
	<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center","orientation":"horizontal"}} -->
	<div class="wp-block-buttons">
		<!-- wp:button {"width":50,"style":{"color":{"background":"#000000","text":"#ffffff"},"border":{"radius":"50px"}}} -->
		<div class="wp-block-button has-custom-width wp-block-button__width-50"><a class="wp-block-button__link has-text-color has-background" style="border-radius:50px;background-color:#000000;color:#ffffff">Contact us</a></div>
		<!-- /wp:button -->
	</div>
	<!-- /wp:buttons -->
	<!-- wp:spacer {"height":64} -->
	<div style="height:64px" aria-hidden="true" class="wp-block-spacer"></div>
	<!-- /wp:spacer -->
</div>
<!-- /wp:group -->

In effect, in the final HTML rendered on the site, we would see the following changes applied:

- <p data-wp-pattern-html="content.paragraph.content" class="has-text-align-center has-small-font-size" style="line-height:.9"><strong>GET IN TOUCH</strong></p>
+ <p  class="has-text-align-center has-small-font-size" style="line-height:.9"><em>My paragraph text</em></p>

- <h2 data-wp-pattern-html="content.heading.content" class="has-text-align-center" id="schedule-a-visit" style="font-size:59px;line-height:1.15"><strong>Schedule a Visit</strong></h2>
+ <h2  class="has-text-align-center wp-block-heading" id="schedule-a-visit" style="font-size:59px;line-height:1.15"><em>My heading text</em></h2>

The HTML gets processed in PHP with the same mechanism used for directives as for Interactivity API. In effect, whenever data-wp-pattern-html attribute is found, then it reads its value from the content attribute saved with the pattern, e.g. content.paragraph.content. It tells us what is the specific content that matches with it that we can read from the partially synced pattern, e.g. "heading': { "content": "<em>My heading text</em>" }. This allows the processor to replace the inner HTML with the content stored in the pattern.

We might also need other directives like data-wp-pattern-text or data-wp-pattern-attribute so we could inject inner text or change the value for an attribute like src from the Image block.

I created a branch that might better illustrate the idea and show how we could reuse the existing functionality built for directives: WordPress/block-interactivity-experiments#228. The actual implementation would eventually land somewhere in the render_callback of the block where it would have access to the $attributes['content'] object and the HTML generated for the pattern:

gutenberg/packages/block-library/src/pattern/index.php

Lines 29 to 42 in 37d9839

	function render_block_core_pattern( $attributes ) {
	if ( empty( $attributes['slug'] ) ) {
	return '';
	}
	$slug = $attributes['slug'];
	$registry = WP_Block_Patterns_Registry::get_instance();
	if ( ! $registry->is_registered( $slug ) ) {
	return '';
	}
	$pattern = $registry->get_registered( $slug );
	return do_blocks( $pattern['content'] );
	}

---

There are several considerations to take into account with any solution like that the one presented above:

• Whenever we add data attributes to the HTML we need to ensure that the original pattern can be loaded in the block editor without block validation issues, so we would have to teach the block editor to ignore all those markers when validating the block after initialization.
• For the case where the user would mark the content with those markers, we would have to ensure that wp_kses filtering isn't removing them for non-admin users.
• The biggest question is what would be the flow in the UI to mark all those content fields with data attributes that directives process can consume.

[carlomanf]

A partially synced pattern block could exist in a user's content in the following way:

<!-- wp:pattern { 
    "syncStatus":"partial",
    "slug": "call-to-action",
    "content": [
        {
            'core/heading': {
                content: 'My heading text',
            },
        },
        {
            'core/button': {
                title: 'Click me',
            },
        },
    ]
} /-->

This isn't how I imagined it would work. I want to draw attention to an example shared in another issue that I think would struggle to fit into the above format. In the linked screenshot, the orange text is intended to be locked and not editable, while the black text is editable.

I also think that users and theme authors should be able to use the full suite of lock types to compose partially synced patterns, not just the content lock. The linked example would probably use a template lock on the right-hand column, an individual lock on the left-hand heading and a content lock on the columns block.

For cases like these, each block in the pattern instance needs to indicate where it sits in relation to other blocks within the pattern. It seems to be the same task that was identified in the phase 3 roadmap of making post revisions "aware of individual blocks" and able to "roll back individual blocks." In my view, partially synced patterns could automatically invoke the "roll back" procedure to keep themselves in sync.

Thinking more broadly, automatic "roll back" could also be used to prevent changes to locked blocks directly within a post, e.g. through code view. The key difference with partially synced patterns is that the "roll back" would be based on the pattern source rather than the previous revision of the current post. As others identified, though, the same procedure would need to run on both the client-side and server-side.

[talldan]

This isn't how I imagined it would work. I want to draw attention to #50060 (comment) that I think would struggle to fit into the above format. In the linked screenshot, the orange text is intended to be locked and not editable, while the black text is editable.

I think there's still the possibility with this model that you could lock down additional parts of a template to make them completely uneditable. Perhaps that could work using the existing lock: 'edit' api for individual blocks within the source pattern. I could see there being a strong requirement for that in editorial processes, so it's great that you've pointed it out. I suppose one concern is whether block level locking is granular enough. There are definitely some interesting possibilities for where this could be taken, but there's also a need to ensure the scope isn't prohibitively too big.

I also think that users and theme authors should be able to use the full suite of lock types to compose partially synced patterns, not just the content lock.

This seems similar to what @SaxonF suggested above. I need to think on this more, but it feels like it would considerably increase the complexity of this feature. I think one of the advantages of contentOnly is that it significantly reduces the kinds of conflicts that can happen when syncing to the source pattern, making it a much more stable feature.

For cases like these, each block in the pattern instance needs to indicate where it sits in relation to other blocks within the pattern

I do think that needs to be considered, but it isn't particularly obvious what the right solution is, so I think it needs more discussion and experimentation. The data structure that I've outlined is a little bit purposefully naive. Potentially we might consider using generated keys or ids for the blocks. The challenge is going to be that we're dealing with conflict resolution, and no one system is perfect.

It seems to be the same task that was identified in the phase 3 roadmap of making post revisions "aware of individual blocks" and able to "roll back individual blocks." In my view, partially synced patterns could automatically invoke the "roll back" procedure to keep themselves in sync.

I'm having some difficult visualizing this. Would you be able to talk me through an example?

I haven't really talked it through with anyone, but my initial thoughts on the phase 3 revision feature were not so much that every block would have its own revision log (the data requirements for that feel unfeasible to me), but more that there's some clever diffing applied on top of something close to the existing revision logs for posts.

[carlomanf]

Potentially we might consider using generated keys or ids for the blocks.

I was thinking the same thing, which leads well into your next comment:

It seems to be the same task that was identified in the phase 3 roadmap of making post revisions "aware of individual blocks" and able to "roll back individual blocks." In my view, partially synced patterns could automatically invoke the "roll back" procedure to keep themselves in sync.

I'm having some difficult visualizing this. Would you be able to talk me through an example?

I haven't really talked it through with anyone, but my initial thoughts on the phase 3 revision feature were not so much that every block would have its own revision log (the data requirements for that feel unfeasible to me), but more that there's some clever diffing applied on top of something close to the existing revision logs for posts.

Here is some pseudo-code:

- syncedpattern ref=123
  - group ref=456 templatelock=contentonly
    - heading ref=789 content="Placeholder Heading"
  - end group
- end pattern

If my understanding of the lock types is correct, neither the heading nor the group can be removed or styled, but the content of the heading can be edited. Given it's a synced pattern, the styling should also be inherited from the source, so if the styles of heading 789 are updated at the source, a mismatch would be detected and the styles of the heading 789 instance would be automatically "rolled back" to the source version, although it's really more of a "roll forward" in this case. Any changes to the heading content would remain intact because the lock type allows it.

If someone went into code view and removed the ref key from the heading:

- syncedpattern ref=123
  - group ref=456 templatelock=contentonly
    - heading content="Edited Heading"
  - end group
- end pattern

then how I imagine it would be interpreted is the old heading 789 being removed and a new one introduced with no ref key. As the group 456 is content locked, neither of the two operations is allowed, so a mismatch would be detected with the inner blocks of group 456 and the group would be "rolled back" to the version with the placeholder heading.

Again, if the group were removed from code view or its ref key removed or changed, a mismatch would be detected with the inner blocks of the top-level pattern and it would be "rolled back."

A similar effect could probably be possible without the generated keys, but it would be more error-prone.

[talldan]

If my understanding of the lock types is correct, neither the heading nor the group can be removed or styled

I think the group can be as the content only locking only applies to inner blocks, but it would also be possible to lock removal of the group using block locking.

Given it's a synced pattern, the styling should also be inherited from the source, so if the styles of heading 789 are updated at the source, a mismatch would be detected and the styles of the heading 789 instance would be automatically "rolled back" to the source version, although it's really more of a "roll forward" in this case.

Thanks, that definitely helps. I've written a long response here, and I may have made some false assumptions, so apologies if that's the case.

Are you also thinking that it would require a dynamic pattern block and similar implementations in PHP and JS? In my mind, that's the main way to get the 'update everywhere' feature of synced patterns working.

I think the main difference between the proposals:

• It allows mixing different types of locking, which is definitely powerful, but needs some thought around UX.
• It uses a key system to match content to the source pattern, though this is an option in both proposals.
• The pattern instance content is serialized, which implies parsing it on the server? The limitation of not being able to source html attributes in PHP would need to be solved.
• You propose using more of a diffing system rather than interpolation of data into a template. I'm guessing it would be a diff of the block tree rather than the markup?

Some potential risks:

• I'm not sure diffing would produce stable enough results. I think even the best systems that look like they work seamlessly tend to lean towards either destructiveness or accepting both sides of the diff (the latter isn't an option here). This probably requires a proof of concept. I think the good thing is any solution in this space can be rigorously unit tested.
• The serialized inner blocks of the pattern instance would ideally be kept up to date with the source fairly regularly (to avoid it falling very far behind). This is ideal for the same reason that git branches are kept regularly up to date, older code is harder to refresh. I think the only way to update the pattern instance outside of loading the editor is to serialize it server-side, which is not currently possible.

Both of those are the main reason I went for an approach where the content attributes are saved in an extracted form and then interpolated. The main mismatch that can happen is with the 'keys', and it would probably mean falling back to the placeholder value, but it is a minimal risk and shouldn't produce invalid block markup (as long as the source pattern is valid).

I do think there's an upgrade path to something like what you propose if those issues can be solved, so maybe my proposal is a stepping stone.

[carlomanf]

Are you also thinking that it would require a dynamic pattern block and similar implementations in PHP and JS? In my mind, that's the main way to get the 'update everywhere' feature of synced patterns working.

Yes, that's what I was thinking.

• The pattern instance content is serialized, which implies parsing it on the server? The limitation of not being able to source html attributes in PHP would need to be solved.
• You propose using more of a diffing system rather than interpolation of data into a template. I'm guessing it would be a diff of the block tree rather than the markup?

In terms of the server-side implementation, the way I imagine it might work is both the source and instance would be parsed separately, to produce two block trees, and the source tree would be used as information to transform the instance tree before rendering it.

[glendaviesnz]

To try and help with exploring/testing possible implementations of this I have added a PR here which adds an experimental flag for Pattern block enhancements.

As a starting point if the flag is enabled and a Pattern has a syncStatus attribute set to partial a wrapper is added around the pattern's blocks and templateLock is set to contentOnly on the innerBlocks. This is obviously going to change quite a bit based on the above discussions in order to get partial syncing actually working, but it at least gives us a starting point of having Pattern block wrapper left in the post content within which to work.

Patterns without the syncStatus attribute just continue to work as in trunk.

[bvlgn]

I am wondering what would/should happen when a block in the source pattern is transformed. How would such a change be synced? Would a block level key system provide enough info or would it need a attribute level key system?

[gziolo]

The same applies to when the block gets removed from the source pattern. We should ignore the user-provided content if it wasn't mapped to any matching part of the modified pattern. We can always mitigate the chances it happens by creating a more reliable system where individual blocks with content can be annotated with a unique identifier that can be retained in a new block when using block transforms.

[talldan]

I've the description with some of the feedback. Notably including the ideas from @gziolo's post on how the source patterns could indicate which parts of the pattern can be replaced (see: #50456 (reply in thread)), and how they would be transformed.

[dmsnell]

Hello all; some great conversation here exploring the design space. Yesterday I spoke with @gziolo at length on a call and wanted to share some ideas we discussed. I've been watching this issue and thinking a lot about it for some time. Starting a new discussion thread here to escape some long reply chains.

I'm very consistently confused trying to understand the various proposals and problem statements and solutions. Much of this surely stems from the large combination of extremely generic words: "block," "pattern," "sync," "partial sync," and "content." I sympathize very much here because I find it incredibly difficult myself to talk about any of this without falling back to these same overloaded terms. I will try to be specific here, but I do believe that the lack of clarity around our vocabulary indicates that we still have opportunity to better understand what we want.

I'm also confused because I think many of the conversations (both in this thread and also in other issues and places) talk about at least three separate concepts as the same thing, or at least we talk about three different purposes for creating these things we want to mix and match:

• we have marketplace creators who want to provide well-designed block arrangements for site authors to download and reuse with their site's customizations
• we have site owners who create an arrangement of blocks and decide they want to reuse that arrangement in various places, but where each place might customize some part of it
• we have site owners who use a block arrangement from the marketplace but want to modify some part of it, or they want to use their own arrangement and modify some part of it, all the while retaining a linkage back to the arrangement from which it came

I want to propose another concept that I believe could ease the confusion. This new concept is (again for lack of less generic wording) a kind of block templating.

We have talk about separating data and presentation, but when I assess some of these proposals what I see is not a real separation, but pushing "data" or "content" into the block JSON attributes while leaving it coupled with the presentation inside the same block. A real separation completely severs that blocks that provide inner content from the block specifying where they belong. We also have a framework in place that lets us do this: inner blocks.

Much of the confusion stems from the fact that we have no solid way to declare placeholders for content. This is a problem we've been actively working on solving and have multiple candidate solutions for.

What @gziolo and I discussed essentially forms around a template block whose first inner block is the "format string" just as it is in sprintf() or date() and whose remaining blocks supply the content referenced in that "format."

This simple idea only relies on existing code and existing concepts, apart from the placeholder, which itself could be created as another block whose type means "I am a content placeholder."

What are some of the prime motivators behind such a structure?

• This eschews the concept of locking. In essence, everything is locked unless it's explicitly opened for extension. The only way to provide the ability to modify a pattern is to introduce a placeholder or copy the pattern into a new one with the wanted modifications.
• It eschews the concept of the "content role" because the data being supplied to the pattern comes from the outside and there's no need to create such a new concept.
• It's composable because data provided in the inner blocks can cascade into a nested pattern. It's easy enough to imagine storing a name mapping in the block attributes for the outer template block specifying "headlinePromo is provided by the third slot in the inner blocks." In the rendering pipeline all these slots can provide their content as a context that inner renders use. This means that automatically we can overwrite data provided by some other template.
• There's no distinction between a default value and user-supplied values. There's nothing special about the format block. If creating a pattern on the marketplace I can wrap my pattern in the template block and provide the additional inner blocks which supply the default values. If I'm a site author and I select a few blocks, I can click "Turn into a template" and they will be wrapped in a group which becomes the format block.
• If someone wants to modify a pattern, all they need to do is click "copy this pattern into a new pattern" which they can modify. Only the elements they change will be different. If we want, we can store a source attribute of some kind linking the new pattern back to the one from whence it came.

This is trivial to handle on the server render because it embraces the same data design language that powers blocks. Everything is just a block. It's also a heavy up-front cost because we have to design new flows in the editor to properly display and edit these templates, but then again, we have to do a fair amount of that either way regardless.

The entire problem of diffing patterns and auto-updating derived patterns is a difficult task I think is best scoped out of the one of solving the "synced patterns" problem. Specifically there's no automated way we can determine what the right thing to do is; plus there are a host of simple solutions that let a site author determine the best resolution, because we can know that patterns updated without trying to resolve inherent ambiguities.

In the given approach, by separating the format block from the data placeholders we can choose to have the format as <!-- wp:pattern ref=[...] /--> and so now without doing any work, without designing any system, we're still able to keep that pattern fully "in sync" while providing our own content.

This comment is radically terse for what I'm tossing out there, but it's long enough and I wanted to share this as an alternative way of thinking about the problem, a way which fully embraces the block model and pushes it into templating. There are more challenges and more benefits, but I believe these challenges are solved or mostly solved. Happy to discuss further.

[dmsnell]

for quite possibly years now (at least a year and a half) I've been trying to find a way to implement sectioning via inner blocks and for some reason the template approach never hit me, even though I think it's kind of staring us in the face.

the other attributes I believe are not a real problem when relying on the template. the main thing is that patterns themselves are not the thing, but simply a stored arrangement of blocks. having a template gives us a lot of freedom and covers a lot of cases that we've been discussing creating new solutions for, but does so without requiring those new solutions.

the idea was probably partly inspired by your suggestions of leaving the pattern alone as-is to avoid breakage.

[talldan]

The things I like about the proposal:

• The user has more control over the the modifiable parts of the pattern
• The idea of 'forking' patterns seems quite powerful

If I'm understanding correctly, is the idea that any block can be placed into any slot? I see some challenges in that the user can reorder the fill blocks in a way that's incompatible. The numerical tokens also don't provide much semantic value, but I'm personally not sure on the best option for that or whether it could be adequately solved in the other proposals.

The entire problem of diffing patterns and auto-updating derived patterns is a difficult task I think is best scoped out of the one of solving the "synced patterns" problem

This would mean dropping a compelling feature. I do wonder if it's worth instead focusing on paying back some debt around reusable blocks/patterns and working on the unification of these features first if this is being considered a challenge that the proposals aren't fulfilling.

[dmsnell]

any block can be placed into any slot?

when asking me personally I will always say yes because I believe that user freedom is more important than preserving a designer's own stylistic preferences on someone else's site. still, I'm sure people will be happy to add locks and filters to prevent people from doing what they want. it's not incompatible with this approach.

The numerical tokens also don't provide much semantic value

These also would in no way make it into the "format string" but merely demonstrate the idea here in this issue. The "Bits" syntax, or dynamic token syntax, would be a more formal placeholder. The "Bits" idea (again, dynamic tokens) are also the magic that make plaintext replacements for attributes possible as well, and do so without forcing us to create new concepts to disambiguate big portals with full rich editing and tiny portals with mostly URLs and simple text.

I've gone through a number of iterations on the idea of leaving these numeric vs. giving them names. It's surprising, but I think the anonymous slots have their own benefits that name can't provide, particularly when wanting to replace the "format string" with a new one, or rearrange the layout.

That being said, there's a trivial solution: map the blocks in the template block's JSON attributes (this is illustrated in my last code example above). The value of named slots/fills comes in strong when we have cascading templates, because names can traverse context in a way that numbers cannot. It may not be clear that the fills attribute is mapping the slots, but there's no numbers in there because the numbers are inherent with the positioning of the inner blocks: we only need to assign names to the inner block ordering.

This would mean dropping a compelling feature.

This is another case where I think that may be the reality anyway. There's an inherent ambiguity that cannot be resolved automatically without breaking very common cases. This proposal doesn't solve the problem this feature intends to, but it also doesn't make it any harder to add that on later.

This is a tangent, but if you ask me, I would suggest the very best thing we can do for diffing changes from source patterns to modified local patterns is nothing. Link the origin pattern when "forking" (that's a good term, where I had used "copy" or "clone") and if we detect any updates to the source then flag that somehow to the site author who can manually resolve it. Manual resolution can be trivial and the user can always choose what they want to updates. Doing it automatically is trying to work around the laws of physics, and that never works out well.

There are cases we can update via diffing, but also way more that we cannot, and who is to say that just because something doesn't present an inherent textual conflict that it's an intended change. git shows us that there's plenty of opportunity to merge two changes without conflict on a purely textual basic while still introducing application-level breakage.

Or maybe we just ask AI to do it. My point is that templating of block patterns can be solved independently of this massive feature and isolating them from each other might help bring both sides to a better end sooner than trying to do them as a single project.

[talldan]

I've started developing a proof of concept of this in #51042. It's very rough around the edges right now, but sharing early so that folks can follow along and collaborate.

[eric-michel]

I am a site developer for an agency, and am actively making sites for clients using Gutenberg every day. Probably our biggest pain point right now is that the editor does not handle types of content that are mostly standardized with small content customizations per post - things like contact directories, majors at a university, products in a catalog.

For us, the absolute dream scenario is what you are proposing, @dmsnell, except with the inclusion of the ability to alter the primary template and have all of the pages that use that template automatically change as well.

Would it not make sense to designate various blocks in a template as editable on a post-by-post basis, provide an ID for those values, and then save those values in the post meta table? Those values could then be reused or shifted around the template with ease, and the site would know exactly what to output. This follows the old tried and true method of custom fields output via a PHP template, but provides the ease of template creation that Gutenberg provides, along with a more visual editing experience for each post.

For example, let's say I have a directory of attorneys. I create a template in Gutenberg that includes several editable content areas for each attorney page, each of which I provide an ID: work_history, education, specialties, bio, etc. On each attorney page, we (or our client) can add content to those content areas. Later, if I decide that I to move education above work_history, I can simply swap them in the template, and as long as their IDs remain constant, all pages based on that template get immediately updated and the correct content is shown. It's basically the editor equivalent of get_post_meta.

By way of a third party example, I work with Shopify on a semi-regular basis. When creating a template in their editor, almost all content areas have this button available:

This allows you to enter content specific to whatever entity that template is for (a page, product, collection, etc). And because those values are named and saved in the database, I can then completely rework that template and designate those values be used elsewhere.

It's worth noting that the editor already partially works this way. The Post Content, Post Title, and Featured Image blocks are basically what I'm proposing. I'm just asking that we go a step further and allow any content of any block within a template to be designated as editable and saved for reuse on a page-by-page basis. In a perfect world, I could even see specific settings being set as editable. For instance, adding a Cover block to a template, and designating the background image as an editable value for each post that uses that template.

I also believe that this would be a natural progression for developers who are used to creating sites in WordPress pre-Gutenberg because it so closely follows the output-post-meta-on-a-template paradigm that's existed for years, but does so in a way that dramatically increases template development speed and provides a nice visual editing experience for each post as well. It also helps address the valid concerns of so much new jargon.

Disclaimer: I freely admit that I only know enough to be dangerous, so there may be laughably ignorant assumptions I'm making here about what is possible. This is simply from the perspective of what would be the ideal solution to so many problems we run into as an agency.

[glendaviesnz]

One use case I was pondering, which may or may not be valid, but which may affect the implementation detail, is the injection of custom content into the pattern from an external source rather than from a user interaction. One use case of Patterns I can see is for the addition of unique starter content that is generated by AI.

There is some debate about whether it is better to get AI generated content from an LLM as structured JSON rather than the full block syntax. If it is some sort of JSON structure, then for the likes of site starter content you might say "I want a cover block for a coffee shop called Dan's Filter Coffee" and instead of getting cover block syntax you would instead get something like:

{
  "block":"home-cover",
  "content": {
        "heading": {
            "content": "Dan's filter coffee"
        },
        "paragraph": {
            "content": "If you hate filter coffee then you obviously haven't tried Dan's"
        }
    }
}

This could then easily be injected into the pattern by overriding the relevant attributes if using the approach outlined by @talldan and @gziolo, but it seems like it would take more of a search/replace approach if using the placeholder approach @dmsnell suggests. But I may be overlooking something, and as mentioned, this may in fact not be a valid use case, just putting it out there in case it is something we need to take into account.

[gziolo]

If you consider content placeholder blocks with only a single two attributes being the the name and the value (sourced from the saved value – innerHTML) then you would have the block after parsing looking like this:

[
	{
		"blockName": "core/token",
		"attrs": {
			"name": "heading.content"
		},
		"innerBlocks": [],
		"innerHTML": "Dan's filter coffee",
		"innerContent": [
			"Dan's filter coffee"
		]
	},
	{
		"blockName": "core/token",
		"attrs": {
			"name": "paragraph.content"
		},
		"innerBlocks": [],
		"innerHTML": "If you hate filter coffee then you obviously haven't tried Dan's",
		"innerContent": [
			"If you hate filter coffee then you obviously haven't tried Dan's"
		]
	}
]

To replace them with something else, you could probably simply remove the existing tokens and put different tokens instead. It's even simpler the replacing content in HTML as every token with content provided by the user or AI is atomic so you don't have to worry about any type of lookup other than matching attrs.name when willing to replace something on the server.

[glendaviesnz]

ah true, thanks, I was overlooking the parsed version of the blocks in relation to the placeholder version, that does make for an easier match.

[gziolo]

I explored further the idea of using a special block type to store the content in #50777 to better illustrate the idea. I was also trying to figure out if we could use the slot & fill pattern to render the components from the Template Content blocks inside the marked placeholders in the pattern that provides the design part. I didn't succeed so far and it feels fragile. It would be an alternative approach to what @talldan explores in #50649 which tries to find a way to edit content in a different place in the block tree.

[gziolo]

There is one more important consideration that I discussed this week at length with @ellatrix and @dmsnell, how to handle the case when someone deletes the pattern that provides the design/presentation aspect of the Partially Synced Pattern. Today, the problem doesn’t exist because we always copy/detach the blocks when inserting the pattern. In the case of Reusable Blocks, we only store the ref, so when the block gets removed we show nothing.

It gets more nuanced when entering the world of blocks that store unique input from users and only reference the design aspect. Do you think that site authors will feel comfortable showing nothing on the site when they can’t load the design? What sources for the pattern’s design do we plan to offer? Some possibilities:

• pattern from Block Pattern Directory
• pattern from the theme
• pattern from the plugin
• pattern sourced from Reusable Block
• pattern registered by the site

If necessary, we could always create a local copy of the pattern as soon as it gets used with the Partially Synced Pattern.

[SaxonF]

we could always create a local copy of the pattern as soon as it gets used with the Partially Synced Pattern

This is behaviour I would expect to see and more closely mimics existing design tools. I don't think we should attempt to replace with another pattern. Webflow even goes as far as blocking the ability to delete a component if it's in use on the site which might be an acceptable starting experience. Regardless of the approach it's important we have the ability to highlight where a synced pattern is being used (x number of instances).

[talldan]

If necessary, we could always create a local copy of the pattern as soon as it gets used with the Partially Synced Pattern.

There's also then a situation where the fallback needs to be synchronized, or there's the risk of it becoming outdated when compared to the source pattern.

There isn't an easy way to push updates out to instances of patterns, which I think is the main problem we're grappling with here. Instead we're relying on instances using a pull system to receive updates.

Similarly there's no easy way to count instances without parsing all content, but I agree that is important.

[gziolo]

It seems like we are going to start with the hard requirement that a Partially Synced Pattern can work only with another pattern that is stored locally on the website and always available.

[glendaviesnz]

I briefly explored the option of adding a Pattern Part block as a way of keeping changes to individual block content/settings much closer to the block in question rather than pushing them up to the parent Pattern block and then having to track which block it came from.

However, it adds a lot of layout issues and complexity in the Editor with all the additional divs added. It may be possible to make them useful without needing to show them in the Editor, but not sure how, so have shelved them for now. Just noting here as a record of things that have been explored.

[gziolo]

I wanted to reshare my #50649 (comment) for visibility. I left it under the exploration from @talldan where he was trying to synchronize inner block attribute updates to a partially synced parent pattern block. I've been playing with two different prototypes to see whether we can avoid changing the block editor store and/or overloading setAttributes passed as one of the props to all blocks through the edit implementation.

First, I started with #50777 implementing the concept of converting all template content data into virtual blocks named core/template-content that try to portal the editable field into the design block. That would be some sort of slot & fill approach where the pattern with the design replaces RichText or PlainText with a slot, and the special template content block would handle the fill that handles setAttributes and the holds the value as the attribute. It was inspired by the concepts outlined by @dmsnell in #50456 (comment). However, I tried to take a shortcut by avoiding any modifications to the block editor store or the parsing mechanism. I also went to granular by trying to replace the components that edit individual attributes. I think that to make it work, we really need to take a deeper dive into how the block parsing works so we can pass down the blocks that represent content to the template block that contains placeholders so they can be replaced before rendering the block editor's UI.

---

I switched to another prototype that is still in progress, but you can watch the progress in #50901. It should be compatible with the ideas explained by @dmsnell, because the PR concentrates on the editing experience by storing a local copy of the pattern with edits applied to the content. I'm trying to understand how we can build the editing workflow in the block editor that allows to merge the design coming from one pattern with the content coming from another pattern. My initial conclusion is that the simplest model for editing would be the one that always uses the local copy of the pattern providing the design (from wp_block post type) with the template lock enabled that allows only changing content. A simpler alternative would be to allow edits on the block level for those picked by the author of the source pattern. The whole challenge would be to mark every block that can receive edits with a unique name stored in block metadata represented in HTML comments. Optionally, we could also list the attributes that can be edited if we really want to make it so granular. Once we have it in place in both the source pattern storing the design, and the copy where we edit content, we can parse both HTML representations and use the marked places for all necessary transformations.

---

Some high-level thoughts based on the explorations above.

• We could store the local copy with edited content on top of the source pattern that provides the design in the Partially Synced Pattern. As long as we can identify whether there were no changes applied to the design of the source pattern, then we can always display the local copy in both the editor and for the site visitors. This way, we can avoid all the processing. If the design changes, we can always update the local copy when editing in the block editor. On the front of the site, though, we would have to run dynamic processing in that case.
• We could build something working faster if we were to start by making the block the way to distinguish what the user can edit. So, the scenario would be that we put a metadata attribute on the pattern with the pattern representing the design that tells the editor that this specific block is going to be unlocked for content editing in the block editor. That would make the processing simpler, as we can replace the whole block in both the editor and on the frontend whenever the source design changes.

[merijnponzo]

Like @gziolo says

• Optionally, we could also list the attributes that can be edited if we really want to make it so granular

Maybe you can have a kind of a 'attributes bridge' to sync your Patterns.
However, on the serverside this would mean lot's of checking and replacing attributes

I don't have any clear idea's on how to tackle this but for a starter i made a kinda example of syncing and unsyncing attributes between blocks and patterns.

It would be nice that you can sync & unsync styles as well content

[SantosGuillamot]

Maybe you can have a kind of a 'attributes bridge' to sync your Patterns.

Actually, I belive this relates to the proposal to connect block attributes and custom fields. Whatever mechanism is designed for that, could potentially be applied here as you suggest.

[glendaviesnz]

Actually, I believe this relates to the #51373. Whatever mechanism is designed for that, could potentially be applied here as you suggest.

I have had a look at whether the connecting block attributes and custom fields might be a way forward for implementing partial syncing of patterns, and it looks like it has potential:

partial-sync.mp4

In the above, I just enabled the Connections experiment. There would be a few extra details to sort out to get this to a production-ready form though:

• There needs to be the option to have fallback content for the fields, so the custom field content will be displayed if it exists, otherwise, the default block content will show.
• The pattern creator should have a way of easily indicating which parts of the synced pattern can be edited independently.
• The custom field keys need to be generated automatically and dynamically on a pattern instance basis in order to allow the same pattern to be edited independently more than once in the same post.
• Ideally, the content editing should happen inline in the same way as a normal block edit, so there needs to be some way of easily augmenting the block editing process to save attributes to custom fields when needed.
• We need to make sure the custom field data plays nicely with post revisions, custom post types, etc.

Of the implementation options discussed so far this currently seems like the best approach to follow. What do others think?

[glendaviesnz]

I have added a tracking issue for the work around using custom fields for partial syncing.