I was talking with @nb and the topic of alternative approaches came up. Pasting my thoughts here, in case someone has any opinions on the matter. I'm pretty convinced that the redux approach that this PR takes is the right path, but I've been wrong before! 😄

The big alternative approach I’ve been mulling over is to enhance the Gutenberg blocks API to the point where reusable blocks could be added as a plain old block type that doesn’t need to touch redux at all.

To do this, the blocks API needs three things:

1. Some way of letting blocks have internal state (think setState) that can be initialised from data that is passed into createBlock. This could be as simple as having the API let you mark an attribute as being private or non-serializable.
2. Some way of letting you provide a higher order matching function instead of a blocks array when defining transforms.
3. To pass the complete block in on calls to transform() instead of just the block attributes.

If we had these things then reusable blocks could, I think, look something like this:

registerBlockType( 'core/reusable-block', {
    ...
    attributes: {
        ref: { type: 'string' },
        _referencedBlock: { type: 'object' } // the underscore denotes that this is "private" 
    },
    transforms: {
        from: [
            {
                type: 'block',
                match: ( destinationBlock, sourceBlock ) => destinationBlock.name === sourceBlock.attributes._referencedBlock.name,
                transform( sourceBlock ) {
                    return createBlock( sourceBlock.attributes._referencedBlock.name, sourceBlock.attributes._referencedBlock.attributes );
                }
            }
        ],
        to: [
            {
                type: 'block',
                match: () => true,
                transform( sourceBlock ) {
                    return createBlock( 'core/reusable-block', {
                        ref: uuid(),
                        _referencedBlock: sourceBlock,
                    } );
                }
            }
        ],
    }
} );

Pros:

• Feels nice having reusable block be just a block.
• It's a lot less code.

Cons:

• API changes feel a bit awkward and hacky.
• Will likely need to use redux anyway to show reusable blocks in the Inserter.
• Reusable blocks aren’t a native part of the editor—will make it hard to extend this feature in the future.

OK, most of the major pieces of reusable blocks are now implemented. I'd love to get some initial feedback on this PR before I start adding tests, cleaning it up, and breaking it up into smaller PRs! ❤️😃

Here's a lil' demo:

cc. @nb @mtias @westonruter @jasmussen

This looks great @noisysocks

If I am not missing, the possibility of making multiple blocks or a group of blocks reuseable is also on the roadmap after this?

Good question, @munirkamal! I agree with @jasmussen's sentiments in #1516 (comment):

Now the mockups got me so excited, but what they in fact depict, should probably be for V2 of Gutenberg. And they should probably take advantage of block nesting (see #428). So you could imagine first inserting a "Group" block, and then moving a number of blocks inside that group. Once that is done, you can once again make that single group block into a reusable block.

@noisysocks

That makes sense, and I also agree with what @jasmussen suggested there.

Keep up the great work folks, Gutenberg is coming along really well.

Awesome work here!

Before digging into the code, I'd like to think a bit about the "modal" for the reusable block interactions and whether it's a good flow or not.

How does it work now:

• You try to edit the block, and once the onChange is catched, we ask the user if he wants to update the reusable block or detach from the original block
• If you detach, it's quite obvious, you'll be presented with a "local" block, and the reusable link is "lost"
• if you updated the reusable block, the question is, when do we ask the user again if he want to continue editing the original block. For now, this is being done when remounting the component (for example moving to text mode and back to edit mode), but this is not ideal. A slightly better approach would be to persist this in local state and never ask until the user refreshes the page.

But still, I find this confusing.

I'd suggest the following flow if possible:

• Preset the user with a read-only version of the block (calling the save function of the reusable block)
• Show only two buttons in the block toolbar: Edit and Detach
• Edit triggers the edit mode of the reusable blocks, showing a modal (or in place) the edit function of the reusable block and persisting this change when we "submit" it (we need a submit button in this edit mode)
• Detach behaves like the current approach.

cc @mtias

Thanks for your thoughts @youknowriad!

I agree that the modal is a little confusing. Something I've been noticing too is that it's especially confusing when there are multiple instances of the same reusable block in the post.

I like the toolbar idea—I'll spend some time experimenting with this approach! 😄

Would be good to get @jasmussen's opinion on this.

Great work all around, and great thoughts too. I think the modals work fine, but I also think Riads suggestion is potentially better.

This is such a nice feature, it might be worth looking at it in two phases. One which features the modal as it is — seems like it might be worth getting this PR merged in and tested as is.

Then in phase two we can take the learnings from V1 and look at the UI improvements that Riad suggested. Unless of course there are technical underpinnings that would need this to change sooner rather than later, in which case I'd defer to Riad (and correct me if I'm wrong).

In both cases, we should do something about the visual appearance of the global block, if we can. Just like how collaborative editing has a colored border, we should have a distinguishing look to a block that is registered as global. It could, for example, have a dashed line instead of the solid line (and the way to do this as we learned from the collab editing stuff is add a CSS class to global blocks and assign the dashed border there).

I do agree with Riad that if the block appears to be completely like other blocks, editable and all, it's easy to forget that it's global, and the modal then becomes jarring. Perhaps an intermediate fix is to dim add a very subtle gray dimming overlay to the entire block (perhaps instead of, or in addition to the dashed border), change the cursor to a pointer instead of the caret. You'd then be able to click the block to get the "detach" prompt, instead of having this happen onChange.

Robert brought to my attention a problem with the idea suggested above:

I do agree with Riad that if the block appears to be completely like other blocks, editable and all, it's easy to forget that it's global, and the modal then becomes jarring. Perhaps an intermediate fix is to dim add a very subtle gray dimming overlay to the entire block (perhaps instead of, or in addition to the dashed border), change the cursor to a pointer instead of the caret. You'd then be able to click the block to get the "detach" prompt, instead of having this happen onChange.

In this situation you couldn't ever select a block (to move it or delete it, say), because that would trigger the prompt.

Which means we're back to either being fine with the onchange prompt for V1 and then making Riads suggested improvements for V2, or doing those changes before merging. I'm fine with either, but would defer to @karmatosed, @mtias or @youknowriad's feelings on this matter.

However you are able to edit a global block, it should still have a distinct style, seems like it's worth trying with a dashed line.

After further discussions with Robert, we mocked up this:

That's what happens when you select a reusable block — a panel at the bottom pops out at the bottom. When the block is just selected, it has "Edit" and "Detach" buttons, as well as a name there. When you've clicked "Edit", the name becomes editable, and there's a "Save" button there.

Thoughts?

Also, is that still a V2, or should that be V1?

Also, is that still a V2, or should that be V1?

I'd be happy to do it for V1. The two approaches are much of a muchness, code wise. Removing the modal would feel kind of nice since it'd mean one less <Slot> in the app.

I replaced the modals with the panel that @jasmussen and I discussed. Here's a GIF:

Check out this video for a higher quality demonstration.

I'm really into it. Thoughts?

@noisysocks Nice, that looks good!

Question: are the "Edit" and "Detach" buttons as well as the title field hidden when the block is unselected? If so then 👍 👍 — see also https://github.com/WordPress/gutenberg/blob/master/docs/design.md#block-design-checklist-dos-and-donts-and-examples

Can you make it so the panel itself either has a background (imagine that quick doodle above had a gray background same as the border color), or a border separator above the fields? Just sort of separate content from chrome so to speak.

Does it work well on mobile? I.e. does it use available space in a good way? Remember you can use flexbox if you need the textfield to resize to available space. Buttons might be localized and grow bigger.

Given those tweaks I think we're ship shape to go!

@jasmussen this should be handled the same way in which we'll handle blocks that save to places outside of the post (i.e a site title block). Those blocks, at least in the post editor incarnation, would likely need their own "save" mechanism for clarity, so they should all do a similar thing.

are the "Edit" and "Detach" buttons as well as the title field hidden when the block is unselected?

Yep! It looks similar to what happens at the end of my demonstration when I click the Detach button.

Can you make it so the panel itself either has a background

It has a light grey background right now. You can't see it in the low quality GIF, but if you watch the the video that I linked to, you'll spot it 😄

Does it work well on mobile?

Good point. I'll spend some time optimising it for small screens today.

Tweaked the styles a bit. Here's how it all looks now:

Desktop	Mobile

I like those changes, nice work 👍 👍

@mtias as I'm still trying to grok the full extent of your comments above, can you chime in also? Thanks.

Codecov Report

Merging #2659 into master will increase coverage by 0.44%.
The diff coverage is 58.49%.

@@            Coverage Diff             @@
##           master    #2659      +/-   ##
==========================================
+ Coverage   34.37%   34.81%   +0.44%     
==========================================
  Files         196      199       +3     
  Lines        5792     5885      +93     
  Branches     1019     1024       +5     
==========================================
+ Hits         1991     2049      +58     
- Misses       3217     3250      +33     
- Partials      584      586       +2

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 21677e3...5637827. Read the comment docs.

I've moved some things around, cleaned up some of the redux actions, and added these really simple progress and failure states to the UI:

I think this feature is looking pretty good. I'm going to start breaking it up into smaller PRs that are easier to review and merge 💃

@noisysocks Nice job so far, I'm fine with merging this PR directly without splitting, Could you rebase it, now that the REST API is merged? It'll make reviewing easier :)

I've moved some things around, cleaned up some of the redux actions, and added these really simple progress and failure states to the UI.

I wonder if these are better as global notices (the post published one), as it provides a consistent place for their display. I can see the proximity being useful, but also can see how it could be missed if you scroll, look elsewhere. cc @jasmussen @karmatosed

I think I agree with Matías, it seems like notices would be a good place for this. Although I'm conflicted because it totally makes sense if there's a spinner in the area that's saving, it makes sense to see message in context of that. Tammie, final word?

I think the "save" button could have the same treatment we use for the "publish" button with the stripes. That signals something is happening. But the confirmation then happens via global notices.

@aduth: Thanks so much reviewing! I've addressed or responded to your feedback.

I think the "save" button could have the same treatment we use for the "publish" button with the stripes. That signals something is happening. But the confirmation then happens via global notices.

@mtias: Great idea! I've implemented this in ec61310a7ce17982aa199cea5e53b4bb294a54a6.