'Inherit query from template' setting is confusing

[jameskoster]

The 'inherit query from template' setting asks users to comprehend complex details within the context of an already-complex block.

Inherit query from template
Toggle to use the global query context that is set with the current template, such as an archive or search. Disable to customize the settings independently.

There are likely longer-term fundamental changes to make that would eliminate the need for this setting, but that doesn't mean we can't attempt to make the control more intuitive in the short term.

[jameskoster]

One idea is to use a segmented control rather than a toggle. I acknowledge it's a little unconventional for a boolean setting, but I think provides space to better describe both options. Toggles work better for really intuitive settings, but in this case it oversimplifies.

cc @WordPress/gutenberg-design for feedback.

[carolinan]

Can we find a way to inform users when the default query does not work? Like in the post content, or in a custom page template.

[paaljoachim]

Thank you for adding this issue James!

Thinking out loud / brainstorming.

Looking at the phrase used today:
"Toggle to use the global query context that is set with the current template, such as an archive or search. Disable to customize the settings independently."

The following words can be difficult to understand: global query context ........ in current template
One has to know what global and query is and what is meant with the current template. A lot to try to understand within one sentence.

Ideas....
Toggle off to customise which posts are displayed.
Toggle on to use default query, such as an archive or search.

The main issue is to make it easier to understand what is going on here with as few as possible words. The more words the more difficult it can be to not understand what is going on. Explaining what happens with toggle on or off can be helpful so the user understands what both do.

[jarekmorawski]

Love those suggestions, @paaljoachim. I'd only include filters in the help text because they also modify the query and it's rather common for people to display a filterable list/grid of posts or other items.

If we stick to a toggle, we should only use one copy variant to avoid confusing people ("is the feature enabled or not?"). In that case, Jay's early suggestion can work better, allowing us to describe each outcome clearly.

What if we put the button in a dedicated Content section? I tweaked the copy a bit to make it feel actionable, practical, and concise. I also replaced template with page because, well, on the front-end the block will always be shown on a page and never in a template.

[jameskoster]

Good input, thanks y'all.

I also replaced template with page because, well, on the front-end the block will always be shown on a page and never in a template.

Maybe we could even simplify even further: "Use the default query e.g. category archive or search results". Additionally, since the help text uses the word default explicitly I would lean towards that being the label control too. 'Follow' seems a bit ambiguous to me.

I appreciate filtering archives is a common pattern in WooCommerce, but it's not really possible (except for search) in core, so I'd probably omit that part for the sake of simplicity. Start with less.

The Content panel is an interesting idea and does resonate. But it would be antithetical with other Content panels, which exist to help users locate editable blocks in the current context. That one might be worth visiting separately.

Can we find a way to inform users when the default query does not work?

This is an excellent point. I can't think of a single use case for a Query inside a Content block to inherit (can you?). Maybe the option should be automatically set to custom, and the control hidden from the UI when Query Loop is placed inside Content?

[jarekmorawski]

Maybe something like this could work? Even simpler. Given the user is editing the block in a template context, we'd inform them what will happen on the front-end.

Maybe the option should be automatically set to custom, and the control hidden from the UI when Query Loop is placed inside Content?

I like that.

[jameskoster]

I feel like we're closing in on something here, and could potentially think about opening a PR, but would welcome wider feedback :)

[richtabor]

Copy wise, can we reduce the technical terminology further? Terms like "global query settings" and 'primary query in a template" don't connect well for most folks.

Maybe something along the lines of:

Use the current template's blog settings to display posts.

Customize which posts are displayed.

[jameskoster]

It's tricky because "blog settings" doesn't really apply to templates like archive.html or search.html which can show more than just blog posts. Maybe we omit that part? "Use the template settings to display entries". Or "Use site settings to display entries".

[richtabor]

"posts" rather than "entries"?

[jarekmorawski]

Could "items" work? We'd then use the copy in other situations, like displaying products, tags, etc.

[kmanijak]

Hey, I made a draft PR with the discussed change: #63739. The copy can be easily tweaked if necessary but we have a base. 🙌

[jameskoster]

Yeah I think it needs to be more generic as there are so many cases where templates can display different post types. Maybe:

Default
Use the template settings to display content

Custom
Customize what content is displayed

[richtabor]

But they're all posts right?

"Content" may be fine, but it feels like a case where being too generic makes it confusing for more people.

[carolinan]

Not always, the query can be used for other post types. We may call them post types, but for a user a page is not a post.

[richtabor]

Yes, but if you're configuring a Query Loop block, I am confident "post" is more relative than "item" or "content", even if it's not a "post". I'm just a bit hesitant to use new words for existing concepts.

Combining the feedback from above, what do you think of this?

Query Type
Default
Display a list of posts or custom post types based on the current template.

Custom
Display a list of posts or custom post types based on specific criteria.

Post Type
Select the type of content to display: posts, pages, or custom post types.

[jarekmorawski]

Sounds good to me! Then QL derivatives like Product Collection could slightly tweak the copy while remaining aligned with the core block.

The only thing I'm not sure of is the button's label. Query Type still sounds technical. Could Content work? The help text specifies what it means in each use case.

I also wonder if the description should say a list of posts or custom post types given that it can be a grid or something else. Maybe it'd just say:

Content
Default
Display posts or custom post types based on the current template.

Custom
Display posts or custom post types based on specific criteria.

Post Type
Select the type of content to display: posts, pages, or custom post types.

[paaljoachim]

Brain storming...

If we aim for the general user then keeping it as simple as possible would be helpful.
The more advanced user would much more quickly pick up what is being said.

Default
Use the template settings to display content

Custom
Customize what content is displayed

The above gives more of a every day language feel to it.

Default
Display posts or custom post types based on the current template.

Custom
Display posts or custom post types based on specific criteria.

Default text. Feels right away more advanced. Mentioning custom post types can confuse quite a few users.

What about just saying Display posts based on the current template.
This would include regular and custom post types.
Now again the word posts feels charged meaning many will have ideas what a post is.
The word Content feels to me that it embraces more than just a post.
I feel like I am circling back to the more every day language text.

[jameskoster]

I appreciate that "Content" could be ambiguous, which is a trade-off. But I also agree that "Custom post types" is starting to sound technical again. The average user will have no idea what that means.

In the spirit of ideas being cheap, here's a different angle:

Default
Configure the query automatically based on the current template.

Custom
Customise the query based on specific criteria.

Yes, "query" is technical, but we're already within the context of the "Query Loop" block, so it's not a new concept.

Side note: I wonder if it's helpful to include a recommendation, IE:

Default
Configure the query automatically based on the current template. Recommended for the main query in a template.

[jarekmorawski]

Yes, "query" is technical, but we're already within the context of the "Query Loop" block, so it's not a new concept.

This makes me wonder if we shouldn't rename the block at some point. Both Query and Loop are words that most non-technical users are unlikely to be familiar with. Something like Posts or even Dynamic Content could work better and be easier to find in the Inserter.

@paaljoachim's suggestion reads well to me. But again, I wonder if we need a help text for Custom at all. Perhaps we'd tell the user what the template's settings are and let them change that instead of using an umbrella term like template settings?

Default
Use the template settings to display content

Custom
Customize what content is displayed

[richtabor]

I appreciate that "Content" could be ambiguous, which is a trade-off. But I also agree that "Custom post types" is starting to sound technical again.

Yea, but only introduced after pages and posts. I think it's important to not make it unclear what the block can do, especially to developers.

[afercia]

I'd totally support a drastic simplification of the (too long) help text for the settings. As mentioned in #58207 the help text could be way shorter. More detailed descriptions and instructions can be provided by using a link pointing to some external documentation. The editor already does that in a few cases.

[kmanijak]

Gave it a try and here's how it looks based on @richtabor 's suggestion:

queryloopinspectorcontrols.mov

[richtabor]

I can't think of a single use case for a Query inside a Content block to inherit (can you?). Maybe the option should be automatically set to custom, and the control hidden from the UI when Query Loop is placed inside Content?

I'm not following. Adding posts to a page, without all the fields for "Custom", doesn't seem like a stretch to me. If it's set to "Default", I get the default posts query, with the standard posts per page count.

[jameskoster]

I totally agree it's a legitimate use case, but that's not how the block works. A Query Loop inside a page inherits from the queried object which is the page itself. There's currently a bug; the canvas doesn't match the frontend:

query.mp4

What you're describing feels more like a case for a variation that queries a specific post type and all of it's associated taxonomies, e.g. "Posts list", "Products list", etc. Related: #40941