Block Hooks: Add UI to inform user about newly added hooked blocks

[ockham]

What problem does this address?

When a user opens the Site Editor to edit a template, it can be surprising for them to see a hooked block that was automatically inserted by a plugin that was recently activated. It's been requested occasionally that the editor UI should alert them to that fact; some of the earliest discussion on this is found here.

(In the above example, the Like Button block was added by a plugin.)

What is your proposed solution?

This could be some sort of notification, or maybe some way of highlighting a hooked block. I'm not sure if we have any pattern or precedent for either; we'll need some input (i.e. mockups) by designers on this.

Implementation-wise, the trickiest part is probably to figure out when to alert the user, and how to persist the information that they have acknowledged it.

We can probably break down the problem into a few smaller pieces:

UI

The UI -- at the top level -- shows which hooked block(s) have been newly added to the current template. It allows a user to acknowledge that, and dismiss the notification. Once dismissed, they won't get the notification for the same blocks again (neither for the current template, nor if they edit any other ones). They'll only get it again if another hooked block has been added.

Determining which hooked blocks have been newly added

On the server side, we know what hooked blocks have been newly added to a template when injecting hooked blocks, and ignoring the ones that have previously been added to ignoredHookedBlocks: The ones that we are injecting are the newly added ones.

Furthermore, we'll know what hooked blocks have been newly added once WordPress/wordpress-develop#6358 lands (which sets ignoredHookedBlocks upon reading), as they'll be available from the difference between $hooked_block_types and $previously_ignored_hooked_blocks here.

The tricky part is then how to communicate this information (i.e. the list of newly added hooked blocks for a given template) to the client.

[ockham]

I've nominated this for a little in-person Hackathon on April 13 -- tentatively with @tjcafferkey 👋

@WordPress/gutenberg-design If y'all have some time, could I maybe ask you to weigh in on this? The ideal outcome would be a mockup that we can use on the 13th to implement this. It's not a blocker for us, since we can always focus on the "Determining which hooked blocks have been newly added" part described above, but it'd be nice to have the visual aspect also covered.

I'll loop in some other stakeholders that have expressed interest in -- and/or have already started -- using Block Hooks in their products for their input/feedback: @simison @pkuliga @jeherve @nerrad.

[annezazu]

This could be some sort of notification, or maybe some way of highlighting a hooked block. I'm not sure if we have any pattern or precedent for either; we'll need some input (i.e. mockups) by designers on this.

This is a rough idea but I could see a snackbar notice working for this for now:

When clicking on "View changes", this would then take you to the plugins UI showing different blocks turned on. The obvious issue with this is that multiple blocks could be added to different places, making it hard to show all of them, and the snackbar goes away quickly. The other option we've used before are more informational like this:

This would only be shown when someone enters a section that has a block added. I wonder if we can reuse some sort of revisions view for this by saving a revision that shows a run down of the changes somehow!

[jasmussen]

I would echo Anne's instincts above with the snackbar, this is the easiest way to start.

Showing second notice Anne suggests also makes a ton of sense in the inspector of the block that was added, though I'd use the light gray version of this, the one you see at the bottom of the unified inspector, "Looking for more settings?" It could simply say, "This block was added by [plugin]."

I'm assuming that the block-addition happens serverside, so no revision would show up.

If you start with those two designs Anne proposed, Snackbar and dismissible notice in the inspector, and that turns out to be insufficient, you could add onto that a welcome guide when entering a page the first time after a block was added. Same component as this:

My instinct is to not start with that, though, as it's pretty intrusive.

[jasmussen]

Oh, and let me know if you need more visuals than Anne already provided!

[ockham]

Thank you @jasmussen and @annezazu!

The obvious issue with this is that multiple blocks could be added to different places, making it hard to show all of them [...]

Yeah, this makes it a bit hard for me to wrap my head around this. The Plugins panel is shown in the block inspector for each individual anchor block, so if a block is inserted in multiple different locations, it's ambiguous which of the corresponding anchor blocks to focus on and have its block inspector opened (e.g. a Like Button that's inserted below the Post Content block, and as the Comment Template block's last child).

The issue is exacerbated if there are multiple different hooked blocks are newly added, e.g. if in addition to the Like Button in the example above, there's also a Shopping Cart block added to the Navigation menu.

(Another way of phrasing the problem is that we don't have a centralized UI for all hooked blocks currently present in the editor that we could have the snackbar link to.)

---

I'm not sure I've fully grasped where we'd put the dismissible notice; if it's supposed to go into the inspector, wouldn't it be a bit redundant at that level when that's where we already have the toggle?

---

I wonder if we can reuse some sort of revisions view for this by saving a revision that shows a run down of the changes somehow!

This is an interesting idea 🤔 As Joen said, insertion of hooked blocks does happen on the server side however, so I'm not sure we could easily implement this. Regardless, I'd be curious what that could look like. Do we already have revisions in the Site Editor (i.e. for templates etc?)

[annezazu]

As Joen said, insertion of hooked blocks does happen on the server side however, so I'm not sure we could easily implement this. Regardless, I'd be curious what that could look like. Do we already have revisions in the Site Editor (i.e. for templates etc?)

Yes! We have revisions for Styles, Templates, and Template Parts. There isn't a good cross connection system for them as is though (which is another pain point I sometimes feel when trying to figure out which revision system to use for which change). I feel like throwing someone in the code view of a template or template part wouldn't be helpful at all (would only add confusion).

I'm not a designer but thinking a bit further down the line, I do think folks will want to see a high level view of how many blocks are added into a template. We hear this a lot already with broader site elements as shown here #60205 In my mind, I'd want to know where this is added too and I know plugins want to clearly communicate this to folks too. One idea, it could be added near revisions at the template inspector level:

I'd still love a way to "review" the blocks being added, similar to the save flow where you can review the changes made. Something like this perhaps when you click on "blocks added" to reveal the following "log" of what's been added (pulled from style revision inspiration):

An alternative off the wall idea, you could click on the blocks added and this would open up each block added with a link to the respective locations to control it but with this central place to return:

Consider this brainstorming (and a fun outlet for me from 6.5 stress 😅 ) until proper @WordPress/gutenberg-design can chime in more. I know those template sidebars are actively being evolved.

I'm not sure I've fully grasped where we'd put the dismissible notice; if it's supposed to go into the inspector, wouldn't it be a bit redundant at that level when that's where we already have the toggle?

With that said, for now, I think a good iteration is what's shared above (snackbar, notice). I don't think it's entirely redundant as it helps explain what it is/why it's there in a way that can be removed, beyond the description. I'm not sold on it though but we do use those more informational notices when we expect confusion.

[ockham]

@tjcafferkey, @gziolo, and I have been discussing the "Determining which hooked blocks have been newly added" part a bit.

@gziolo had a few suggestions on how to communicate the list of newly added hooked blocks from the server to the client:

• We could send the list as part of the response header.
• We could use separate metadata (either solely on the REST API endpoint, or even on the underlying post object).

One existing example is the posts endpoint; when querying a list of posts, the total number of posts is sent along with the response.

[gziolo]

Some examples of using the response headers that I saw this week in the @wordpress/api-fetch package:

gutenberg/packages/api-fetch/src/middlewares/media-upload.js

Lines 66 to 68 in 2b1b80e

	const attachmentId = response.headers.get(
	'x-wp-upload-attachment-id'
	);

gutenberg/packages/api-fetch/src/middlewares/nonce.js

Lines 15 to 18 in 2b1b80e

	if (
	headerName.toLowerCase() === 'x-wp-nonce' &&
	headers[ headerName ] === middleware.nonce
	) {

gutenberg/packages/api-fetch/src/middlewares/http-v1.js

Lines 31 to 35 in 2b1b80e

	headers: {
	...options.headers,
	'X-HTTP-Method-Override': method,
	'Content-Type': 'application/json',
	},

There is also usage in @wordpress/core-data:

gutenberg/packages/core-data/src/resolvers.js

Lines 237 to 244 in 2b1b80e

	meta = {
	totalItems: parseInt(
	response.headers.get( 'X-WP-Total' )
	),
	totalPages: parseInt(
	response.headers.get( 'X-WP-TotalPages' )
	),
	};