FSE: Most site building blocks need previews and placeholders

[jameskoster]

• Site Logo - Add basic example to site logo block #35588
• Site Tagline
• Site Title - Add basic example to site-title block #35590
• Login/out - Login/out block: Add example of the block #62937
• Post Title - Post title: Add example of the block #62955
• Post Content - Post content block: Add example of the block #62968
• Post Author - Post Author blocks: Add example and preview #62978
• Post Comments Count
• Post Date - Post date block: add a block example #63368
• Post Excerpt - Excerpt block: add example of the block #63010
• Post Featured Image - Post featured image: add example of the block #63011
• Post Tags - Post terms block: add an example #63369
• Term Description
• Posts List - Add example for query block and posts list #63286
• Archive Title
• Post Categories
• Next post
• Previous post

Here's a figma file where we can work on this.

[jameskoster]

Some initial ideas for simplest text-based blocks:

Block	Placeholder
Site Tagline	The site description
Site Title	The site title
Login/out	Log in
Post Title	The post title
Post Content	The content of a post, page, or any other content-type. It may include a variety of different blocks like paragraphs, lists, image galleries, and more.
Post Author	The post author
Post Comment	The content of a comment.
Post Comments Count	1
Post Date	[Gutenberg release date?]
Post Excerpt	The excerpt of a post, page, or any other content-type.
Post Tags	Tag
Term Description	The description of a tag, category, or other custom taxonomy.
Archive Title	The title of an archive like a category, tag, author, or date
Post Categories	Category
Next post	Next post
Previous post	Previous post

[carolinan]

I am wondering about this Login/out | Log in because in the editor we are always logged in, should it not be "Log out"?

[jameskoster]

I was thinking about it from the hypothetical visitors perspective, who in most cases will be logged out. It's not a strong feeling though. "Log out" works too :)

[jameskoster]

Post Title | The post title

I wonder what scope there is for these "post" block placeholders to be dynamic. While thinking about the template mosaic view for instance, it would be potentially confusing to see "The post title" in the page template.

If not dynamic, they perhaps need to be even more generic. Consider the singular template which can display posts and pages. What should the Post Title block placeholder display in that case? Maybe something simpler like "The title" would work better?

[jameskoster]

Excluded some of the comment related blocks as these will need to be broken down in to smaller pieces (see #24101).

[jameskoster]

Is there any reason not to use the WordPress logo for the Site Logo block preview (when no logo is set of course)?

[jameskoster]

I worked on designs for the text-based site blocks in figma. I removed the Post Comments Form, Query, and Template Part blocks from the OP for now as they are bit more complex and I suspect they will need dedicated issues to explore in detail.

Site Logo

---

Site Title

---

Site Tagline

---

Login/out

---

Next / Previous post

---

Post Title

---

Post Content

---

Post Author

---

Post Comments Count

---

Post Date

---

Post Excerpt

---

Post Tags

---

Post Categories

---

Archive Title

---

Term Description

---

[carolinan]

Do we just add an empty example in index.js to these blocks, and adjust the width for some?

I can't figure out how to create an example as shown in the images.
For example, the site tagline shows the placeholder text from edit.js, and I don't think that text should be changed to "Just another WordPress site"

[jameskoster]

We've recently updated the placeholders, so we might want to close this issue in favor of one that concentrates on the previews.

The Site Tagline block for example still doesn't have a preview:

[carolinan]

The comment I added above is all about that preview. So a new issue wont help me contribute towards making the preview look like in the image :).

Adding a width to block.json, or the empty example to index.js, displays the current tagline.
If there is no tagline it displays the placeholder text from edit.js which is "Write site tagline…".

[jameskoster]

Ah sorry, I think I misread your comment.

Adding a width to block.json, or the empty example to index.js, displays the current tagline. If there is no tagline it displays the placeholder text from edit.js which is "Write site tagline…".

Is this definitely the behaviour we want, contextual previews? Given our current handling of placeholders the previews could end up being a bit lacklustre. Like the "Write site tagline..." example you shared. As another example, if a featured image isn't set you would end up seeing something like this:

An alternative would be to hard code generic previews – which is how previews for regular blocks work. So when I hover Featured Image I would just see an image in the preview, regardless of whether one is set or not.

[carolinan]

But how? :)
For example, this is the paragraph block. The post/site blocks do not have the "content" attribute.

	example: {
		attributes: {
			content: __(
				'In a village of La Mancha, the name of which I have no desire to call to mind, there lived not long since one of those gentlemen that keep a lance in the lance-rack, an old buckler, a lean hack, and a greyhound for coursing.'
			),
			style: {
				typography: {
					fontSize: 28,
				},
			},
			dropCap: true,
		},
	},

[carolinan]

And I can't find any documentation for the "example" setting in block creation. Guess what shows up if I search for block.json example 😆

[jameskoster]

But how? :)

Good question :D I'm sorry to say I don't know. Perhaps we need to enhance the example functionality in order to account for these data-driven blocks?

[carolinan]

Yes we probably need to invent something new.

[talldan]

Yes we probably need to invent something new.

I stumbled across this issue. Unless this has been solved since your comment, I think we do need something new. There are probably quite a few different ways to solve this, but none of them that I could think of are ideal.

I think the third option I listed below would be my preferred solution. Any other options anyone can think of?

Option 1. Mock block context and entity data in the block definition

These blocks use block context to indicate which post they should read from. It could be possible to mock this data as part of the block definition:

example: {
    context: {
        postType: 'example',
        postId: '1',
    },
    entities: [
        {
            type: 'example',
            id: '1',
            featuredImage: 'https://wordpress.org/example-image.png'
        }
    ],
    attributes: { // ... },
    innerBlocks: [ // ... ],
}

Problems:

• It looks easy, but this could be technically difficult to implement. It'll be difficult to control the context for inner blocks, because the preview is rendered as a single BlockList.
• Bad developer experience

Option 2. Overriding values in the block edit

The simplest option could be to pass example data into the block edit component and use that to override the values of particular variables.

block.json

{
    "example": {
        "src": "https://wordpress.org/example-image.png"
    },

function PostFeaturedImageEdit( { attributes, example: { src: exampleSrc }, ... } ) {
    const isBlockPreview = useIsBlockPreview();
    let [ imageSrc ] = useEntityProp( // ... );
    
    if ( isBlockPreview ) {
        imageSrc = exampleSrc;
    }

    // ...
}

Problems:

• This is pretty simple, but I don't think it's good practice to introduce extra logic to block rendering just for examples. I think it'll reduce code quality.

Option 3. Refactor blocks so that we can create BlockExample components

Blocks could have their presentation logic separated from their business logic. It'd then be easier to create a BlockExample component that renders the same thing as BlockEdit but with dummy data:
edit.js

function PostFeaturedImageEdit( { attributes, ... } ) {
    const [ imageSrc ] = useEntityProp( // ... );
   
    return <PostFeaturedImageEditView src={ imageSrc } />
}

example.js

function PostFeaturedImageExample() {
   return <PostFeaturedImageEditView src="https://wordpress.org/example-image.png" />
}

index.js

// A component can be declared as part of the example.
example: {
    component: PostFeaturedImageExample
    viewportWidth: 500
}

Problems:

• Simple, but refactoring each block could be a lot of work
• Could be open to abuse - e.g. rendering something in the preview that shouldn't be there. 🤷
• This option would never show 'real' data when it's available.

[jameskoster]

Since this issue was opened we've done quite a bit of work around improving the on-canvas representation of these blocks, accounting for context. For example the Featured Image block now displays a placeholder 'graphic' when appropriate.

So perhaps these block previews should just render the block itself (hopefully with the context passed to it). Is that an option?

[annezazu]

👋🏼 Is this issue still relevant? If yes, can we update it? If not, can we close out?

[jameskoster]

A lot of site building blocks still don't have previews.

So perhaps these block previews should just render the block itself (hopefully with the context passed to it). Is that an option?

This still feels like the path to explore.

[MaggieCabrera]

It seems like some of these are quick wins. I started with #62937 and I didn't need to do much to get it to show.

Some others like the prev/next are a little trickier, since it's one block that we want to have two different examples (it's the post-navigation-link block). I wonder if we could just show the title of the post instead for that one and keep one preview for both of them

[carolinan]

In January I started on a block that has these two links, next and prev as inner blocks, similar to how the query pagination block works, I suggest leaving this block and its variation until later and continue with the quick wins. #55157

[MaggieCabrera]

Working on some of these I notice that the preview in the inserter and the one in Global Styles are a little different. It seems like on Global Styles we are adding some extra CSS to alter the appearance and it's not clear to me if they should both look the same or if the differences are ok. Also, some of these are looking broken (like the page list):

Page list

GS	Inserter

Image

GS	Inserter

Button

GS	Inserter

[jameskoster]

My initial thought is they should be the same. What's the reason for different styling in global styles? Maybe @jasmussen knows?

[jasmussen]

They should be the same.

I believe that there may have previously been a difference in how the two are loaded; where one is iframed, and the other may not be (?).

[MaggieCabrera]

They should be the same.

I believe that there may have previously been a difference in how the two are loaded; where one is iframed, and the other may not be (?).

yes, and also, the one in GS is a fixed height, whereas the inserter one has a flexible one, as you can clearly see on the page list example. I could open a PR to align the styles of the two while maintaining a scroll for the GS one.

Also, I'm thinking we want the blocks to be centered when possible, right?

[jasmussen]

Also, I'm thinking we want the blocks to be centered when possible, right?

Yes, though that can be hard when it's larger than the preview. Not sure what flex magic might help there.

[MaggieCabrera]

For context, this is where we added the extra CSS that centers things in global styles: #46727

[MaggieCabrera]

Also, I'm thinking we want the blocks to be centered when possible, right?

Yes, though that can be hard when it's larger than the preview. Not sure what flex magic might help there.

Seems like a CSS puzzle to me, bring it on :D