Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Full Site Editing: Template block names, descriptions, and placeholders #26856

Closed
jameskoster opened this issue Nov 10, 2020 · 21 comments
Closed
Labels
[Feature] Blocks Overall functionality of blocks Needs Dev Ready for, and needs developer efforts

Comments

@jameskoster
Copy link
Contributor

We currently have a variety of blocks with names that are prefixed "Post":

  • Post Title,
  • Post Content,
  • Post Author,
  • etc.

This prefix can be misleading as these blocks will render the content of any post type. When editing a Page template for example, it is confusing to see a "Post Title" block, since that template will only resolve to display pages, not posts. It gets even more confusing with ambiguous templates like Single, Singular, Index...

Below is a table of the existing template blocks along with what I think we should try renaming them to, updated descriptions, and placeholder content where appropriate.

Current name New name New description New Placeholder
Post Title Title Displays the title of a post, page, or any other content-type An example title
Post Author Author Displays the author of a post, page, or any other content-type Author name
Post Content Content Displays the content of a post, page, or any other content-type This is 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 Date Publish Date Displays the date a post, page, or any other content-type was published Todays date
Post Excerpt Excerpt Displays the excerpt of a post, page, or any other content-type This is the excerpt of a post, page, or any other content-type. It may include a variety of different blocks, paragraphs, lists, image galleries, and more.
Post Featured Image Featured Image Displays the featured image of a post, page, or any other content-type Should render the same image we use as a placeholder elsewhere
Post Tags Tags Displays any tags applied to a post, or any other content-type Tag name
Post Categories Categories Displays any categories applied to a post, or any other content-type Category name
Post Comment Comment Displays a single comment This is the content of a comment. It will likely be text only, but may also include images.
Post Comment Author Comment Author Displays the author of a comment Comment author name
Post Comment Date Comment Date Displays the date a comment was published Todays date
Post Comments Comments Displays all comments from a post, page, or any other content-type n/a - should include at least one Post Comment innerblock.
Post Comments Count Comments Count Displays a numerical total of all comments on a post, page or any other content-type 0
Post Comments Form Comments Form Displays a form for visitors to add comments n/a - should display the form

Note: You'll notice the repetition of "a post, page, or any other content-type". I'm sure we can find a more succinct way to say this.

Putting everything together, we can gather a rough idea of what editing the Single template from the Twenty Twentyone theme might look like:

Blocks

Related items:

  1. Placeholder styling should be entirely inherited from the editor stylesheet
  2. Some template blocks are still missing 😓 that is being handled here.
  3. Some existing template block settings may need adjustment
  4. We'll likely need to re-audit these blocks in the context of editing content rather than templates. We can do this in a subsequent issue.
@jameskoster jameskoster added [Feature] Blocks Overall functionality of blocks Needs Dev Ready for, and needs developer efforts [Feature] Full Site Editing labels Nov 10, 2020
@jameskoster
Copy link
Contributor Author

jameskoster commented Nov 10, 2020

Here's a rough example of how the preview would appear in the Template navigation panel:

Screenshot 2020-11-10 at 16 48 29

@karmatosed
Copy link
Member

I myself have to admit seeing a sea of 'post' before blocks did make me think of ways to do this better. This is a great summary @jameskoster.

My own preference would be to remove the 'post' and I think that works in most, if not all cases. I am really keen on the tidying of placeholders, after stumbling onto some myself and finding them to needs some iterations, I really like these suggestions.

@jameskoster
Copy link
Contributor Author

if not all cases

In which cases do you not think it works? Let's refine!

@karmatosed
Copy link
Member

In which cases do you not think it works? Let's refine!

I think for me it's where some are really close to others, it works but it's open to interpretation and that's not solved by removing or not the 'post', there is a deeper issue to also explore. I don't want to derail this issue but will loosely explain. For example, 'tag' results now in:

image

Another, 'comments':

image

Here my concern is between comment and comments specifically. That isn't solved by the post before though, which is why I agree in having this iteration.

@Addison-Stavlo
Copy link
Contributor

In which cases do you not think it works? Let's refine!

The only conflict I see is:

  • Post Categories - it seems there is already a 'Categories' so changing this name would conflict:
    Screen Shot 2021-01-12 at 4 43 59 PM

The other 2 I am lightly concerned with are just a little 'rough' considering close counterparts. They aren't the end of the world, but it seems odd to have one version with a descriptive prefix and one without:

  • Post Title - "Site Title" exists, so changing "Post Title" to "Title" would leave us with the options of "Site Title" and "Title" (in which case the latter makes me question "title of what?").
  • Post Comments vs. Recent Comments - Similarly we would end up with "Comments" and "Latest Comments". Although, the current state having "Post Comments" and "Latest Comments" is still about the same level of confusion IMO so this change doesn't really hurt anything in that regard.

@jameskoster
Copy link
Contributor Author

If we can settle on an appropriate generic prefix I think that would solve these issues, but I'm struggling for ideas there. "Post" is misleading as outlined in the OP.

"Content" feels ok... "Content Title", "Content Author", etc. But what do we do with the Content block? We can't have "Content Content" :D

Perhaps "Entry" could work instead? 🤔

Then again maybe context will be adequate in making the blocks feel intuitive. If I'm editing my product template and see a "Title" block, I think it would be fairly intuitive what the purpose of that block is. Likewise if I'm editing an archive, etc. I'm inclined to suggest that we start with the simplest convention, and expand if required.

@Addison-Stavlo
Copy link
Contributor

"Content" feels ok... "Content Title", "Content Author", etc. But what do we do with the Content block? We can't have "Content Content" :D

Originally I was thinking that lack of prefix might make sense for most of them. And only the ones with conflicts or similar names need to be expanded upon. BUT this does create an inconsistency throughout the group of these entity blocks.

Perhaps "Entry" could work instead? 🤔

Perhaps! Going through this list of blocks and changing "Post" to "Entry" seems like it might be a bit of a step up while preserving the consistency in prefix. Although I wonder how clear "Entry" is as well. Would a new user consider a page to be an entry? If I try to put my NU hat on I could see interpereting 'Entry' as something like a post and not a page as well. 🤔 That said, it definitely has the benefit over "Post" in not confusing between the postType 'post' and the fact that everything is a Post of some type.

@jameskoster
Copy link
Contributor Author

Yeah, I feel like we're combining two subtly different issues here, and they should probably be separated and addressed sequentially:

  1. The "Post" prefix is misleading and should be removed
  2. In the absence of the prefix, the block names might not be clear enough

I think it is difficult to determine whether the second point is true without first seeing how the blocks behave in context. IE when you're in the flow of editing a template / template part.

Like you said, they may feel a little rough, and if they do we can open another issue to explore solutions.

@Addison-Stavlo
Copy link
Contributor

Addison-Stavlo commented Jan 13, 2021

  1. The "Post" prefix is misleading and should be removed
  2. In the absence of the prefix, the block names might not be clear enough

I would add:
3. Absence of prefix has conflicts with some current block names (just 'Categories' I think).
3b. Since one item will still need SOME prefix and "Post" is misleading, we need to come up with an appropriate replacement for "Post" anyways. If that is the case, should we just do that for all of them for the sake of consistency (which also gets rid of the potential "problem 2") ?

@jameskoster
Copy link
Contributor Author

For 3, could we consider renaming the existing "Categories" block to "Post Categories", since that block only returns post categories?

@Addison-Stavlo
Copy link
Contributor

Addison-Stavlo commented Jan 14, 2021

For 3, could we consider renaming the existing "Categories" block to "Post Categories", since that block only returns post categories?

So rename the existing "Categories" block to "Post Categories", and the existing FSE "Post Categories" block to "Categories"? Couldn't this swap create a fair amount of confusion?

@jameskoster
Copy link
Contributor Author

Only if you're a regular user of both blocks, and in that case the icon still offers some familiarity. I don't suppose there are all that many people using the FSE categories block seeing as all FSE features are basically still in beta.

@Addison-Stavlo
Copy link
Contributor

Addison-Stavlo commented Jan 14, 2021

I don't suppose there are all that many people using the FSE categories block seeing as all FSE features are basically still in beta.

True! Although the standard "Categories" block goes beyond FSE.

On a development note, I am not sure if adding backwards compatibility to rename "Categories" to "Post Categories" would be messed up if we have another block renamed from "Post Categories" to "Categories" as well. 🤔 That is, Im not sure if we can swap those markup names core/categories and core/post-categories between two already existing blocks in a good way that is backwards compatible for folks (cc @youknowriad - do you know if there is a good way to handle that in place?), which means if we updated the titles we would have a "Categories" corresponding to core/post-categories and "Post Categories" corresponding to core/categories, which could definitely be a confusing and unfortunate naming mixup.

@youknowriad
Copy link
Contributor

We definitely can't swap the block names (core/*) without breaking changes. Though I'm really curious what we'd want to swap things here ?

  • "Categories" is a block that shows all categories cross-posts (entire site).
  • "Post categories" is a block variations of "Post Hierarchical Terms" block and only shows the categories of the post currently rendered. So these labels and names do make sense to me as they are.

@youknowriad
Copy link
Contributor

I'm not sure I agree with the removal of the "post" prefix in these block names (all of them actually). A "Page" is a "post" in WordPress Land. Post has actually two different meaning in WordPress and in this particular case, we're just using the "Post Type" one. For me it's important to keep the connection to "post type" somehow in the title.

@jameskoster
Copy link
Contributor Author

jameskoster commented Jan 15, 2021

"Categories" is a block that shows all categories cross-posts (entire site).

That isn't true for categories that are added as a custom taxonomy though, correct? For example WooCommerce adds categories for products, but those wouldn't appear in the "Categories" block.

For a site owner running a store more than a blog, I think they would expect a generic "Categories" block to display their product categories. The notion of swapping was to purely make the block name more explicit.

"Post categories" is a block variations of "Post Hierarchical Terms" block and only shows the categories of the post currently rendered. So these labels and names do make sense to me as they are.

So is that block restricted to the post post type? If so, then leaving the prefix is probably fine, but does that mean we'd need separate equivalent blocks for all post types? Should there be a "Page Title" block..?

Post has actually two different meaning in WordPress and in this particular case, we're just using the "Post Type" one.

Totally understand that, but it is a concept that I suspect is lost on the vast majority of users. It seems unlikely that the average person understands that a Page is a post :D

For me it's important to keep the connection to "post type" somehow in the title.

I suppose there are a couple of options there...

  1. As alluded to above... leave things as they are, but create new variations of the Post Hierarchical Terms for the page post type – "Page Title", "Page Content", etc, and restrict all of these blocks to their designated post types.
  2. Change the prefix to something generic that works for all post types. Above we briefly discussed "Content Title" and "Entry Title". But neither felt great. Might we look at template tags for inspiration? "The Title", "The Content"... that might help themers transition.

Any preferences or other options there?

@youknowriad
Copy link
Contributor

That isn't true for categories that are added as a custom taxonomy though, correct?

The block uses wp_list_categories without passing a taxonomy so yeah it's more the post categories by default but this doesn't mean the block can't be made generic and support custom taxonomies just like the Post Categories one.

To give more context the "categories" block was built as a drop-in replacement for the "categories" widget but it should be seen as a starting point.

So is that block restricted to the post post type?

No, it's not, it's for any post type. But it's important to understand that it shows categories of a "single post", the one being rendered. (that could be of any post type). That is the main difference between, the two blocks.

Totally understand that, but it is a concept that I suspect is lost on the vast majority of users.

These Post* blocks are essentially for themers (for now) and I don't really expect these users to not know that. I'm all for finding a better wording but I do think having a prefix here that is consistent across all the Post * blocks is important. It's part of what defines these blocks.

create new variations of the Post Hierarchical Terms for the page post

No, we shouldn't be doing that, that block can be dropped in a "single.html" template and work the same depending on the post type of the post being rendered.

Change the prefix to something generic that works for all post types.

I still think there's history with "Post" being the generic name for these in WordPress and I'm really very unsure whether we should be changing that adhoc in these blocks. I like "Entry" but it's too generic, a category can be an entry too. So I still have a preference for the current names personally.

@jameskoster
Copy link
Contributor Author

I appreciate that most people using the site editor at first will probably be able to understand this convention, but one of the most exciting things about the FSE project is making the theme editing experience more accessible to less tech-savvy users. So down the road I still think that seeing a "Post Title" block in the "Page" template could confuse people.

Atm I am kind of leaning towards "The Title" and "The Content" because it makes sense for any post type and harmonises with the template tags that existing themers will be familiar with. It doesn't translate well to the post editor, but I'm not sure how often these blocks will be used in that context.

Having said that, I am also happy to stick with the "Post" prefix and address it later if needed. For now we can focus on the descriptions and placeholders.

@carolinan
Copy link
Contributor

Are we ready to continue with updating the descriptions and placeholder contents?

@jameskoster
Copy link
Contributor Author

@carolinan yes, we need to. Previews are also missing for most of these blocks. We may need to break this down in to smaller issues though as it is quite a big task. I opened #30029 for the placeholders/previews specifically, which feels like the most pressing item.

@jameskoster
Copy link
Contributor Author

Closing this in favor of #35501

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Feature] Blocks Overall functionality of blocks Needs Dev Ready for, and needs developer efforts
Projects
None yet
Development

No branches or pull requests

5 participants