-
Notifications
You must be signed in to change notification settings - Fork 4.2k
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
Add docs for extending the Query Loop block via variations #44137
Add docs for extending the Query Loop block via variations #44137
Conversation
Detail and explain how to make best use of the changes introduced in the following PRs: WordPress#43590, WordPress#43632 and WordPress#44093
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This guide is amazing! Thank you for writing up such a clear and detailed description.
I left some inline comments where I have some questions :)
|
||
Notice that we have also disabled the `postType` control: when the user selects our variation, why show them a confusing dropdown to change the post type? On top of that it might break the block as we can implement custom controls, as we'll see shortly. | ||
|
||
### Adding additional controls |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Up to this point here this guide is super clear and easy to understand. I personally find this final section to be a little confusing.
The example code uses a isMyBooksVariation
function. I assume that is a custom function that the developer needs to create for themselves. But reading this that isn't really clear.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hey @fabiankaegy, thanks for the feedback. Is the isMyBooksVariation
the only part you find confusing, or is there something else that's unclear?
In my latest commit I changed the comment above the code to this:
// We only want to add these controls if it is our variation,
// so here we can implement a custom logic to check for that, similiar
// to the `isActive` function described above.
// The following assumes that you wrote a custom `isMyBooksVariation`
// function to handle that.
Does it sound more appropriate?
I mean, I can also provide the full code for isMyBooksVariation
, but I wanted to keep the guide focused and not be too railroad-y. What do you think?
You can hook into that filter and modify your query accordingly. Just make sure you don't cause side-effects to other Query Loop blocks by at least checking that you apply the filter only to your variation! | ||
|
||
```php | ||
if( 'my-plugin/books-list' === $block[ 'attrs' ][ 'namespace' ] ) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where would one be calling this hook from so that they have access to the attributes of the block?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So, this would be a bit tricky. Because I don't want to get too prescriptive in this guide and people can take their own route as preferred to access the block. We do it inside a pre-render filter. I will add some info about that, however, I understand this is a bit confusing.
|
||
### Making your custom query work on the front-end side | ||
|
||
The Query Loop block functions mainly through the Post Template block which receives the attributes and builds the query from there. Other first-class children of the Query Loop block (such as the Pagination block) behave in the same way. They build their query and then expose the result via the filter [`query_loop_block_query_vars`](https://developer.wordpress.org/reference/hooks/query_loop_block_query_vars/). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The link https://developer.wordpress.org/reference/hooks/query_loop_block_query_vars
is currently broken. I assume that will only appear with the release of 6.1?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm actually unsure of how it works, that's something I needed to clarify with you folks. I added the URL using the convention I saw, assuming that some sort of script reads the JSDoc of a hook and publishes the updated references. Would that be correct? Or who would I have to ask?
docs/how-to-guides/block-tutorial/extending-the-query-loop-block.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Awesome work here @sunyatasattva! 💯 Thanks so much!
|
||
With the block variations API you can provide the default settings that make the most sense for your use-case. | ||
|
||
Let's go on a journey, for example, of setting up a variation that could fit a plugin which registers a `book` [custom post type](https://developer.wordpress.org/plugins/post-types/). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: I think we can do some rewording here and maybe have a heading for this section as an example use case.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The thing is that the example is spanning through the entire document, so I don't feel like it makes sense to scope it under a section heading.
As for the rewording, do you have suggestions? Or, what's the feeling that you get from this paragraph that puts you off? Is it the phrasing, or the syntax? Let me know so I can provide a suggestion for the rewording. Or feel free to change it!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No strong opinion on the heading.. Regarding the rewording the only thing that felt 'weird' to me was: that could fit a plugin
. Specifically the fit
. I'm not sure if it's just me, as I'm not a native English speaker..
Maybe it can be as simple as changing that could fit -> for
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You're right. Maybe "suit" was a better choice than "fit". But I have changed it with "for" to keep it simple
Your first step would be to create a variation which will be set up in such a way to provide a block variation which will display by default a list of books instead of blog posts. You would start with something like this: | ||
|
||
```js | ||
registerBlockVariation( 'core/query', { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it would be better to add the full block variation here, and then explain the specific parts.
It's also important to note that due to the Query Loop setup with patterns and scope:block
variations , the selected pattern's attribute will be used except for postType
and inherit
query properties.
To elaborate on this, if for example we have set perPage:10
and we select a pattern with a perPage:3
, the resulting perPage
will be 3
. To circumvent this(for now) we need to declare some starting innerBlocks
in our variation like:
innerBlocks: [
[
'core/post-template',
{},
[ [ 'core/post-title' ], [ 'core/post-excerpt' ] ],
],
[ 'core/query-pagination' ],
[ 'core/query-no-results' ],
],
scope: [ 'block' ],
In addition to the above, in the case of having declared innerBlocks
, we need to make sure to add to our variation more attributes(example here). This is because of the core handling of object
block attributes where we set the defaults only if the top level attribute is not set - in our case query
.
I hope I'll be able to fix this for 6.1 to handle specific Query Loop variation patterns, so the extenders could offer specific patterns.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since this PR is going to land now, it would be better to add info about it and we could probably skip some of the details I mention above about the innerBlocks
etc..
} | ||
``` | ||
|
||
Also note that the Query Loop block supports `'block'` as a string in the `scope` property, and it will allow the variation to be picked up after inserting the block itself. Read more about the Block Variation Picker [here](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we can skip this scope
variation paragraph, as these variation are only shown when a user clicks start blank
in the setup of the block.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And don't we want to inform users that this is possible? I find that, especially with #44197, it could be really helpful. At least, that's something we will definitely use in Woo Blocks.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, I think we should skip it. With #44197 a plugin should either register their own patterns for best user experience or just add innerBlocks
to their variations and have the same result in every insertion. Of course it would preferred I think to register patterns..
The scope
variations are really simple variations that few would select, if they have something specific in mind they want to build. I also chatted with Luigi(Woo Blocks) a bit earlier and it seems you had that scope because it was not possible to do it better - before the above mentioned PR. I don't think you should use that scope to be honest and I think the best scope
for such variations would be the inserter
one.
docs/how-to-guides/block-tutorial/extending-the-query-loop-block.md
Outdated
Show resolved
Hide resolved
docs/how-to-guides/block-tutorial/extending-the-query-loop-block.md
Outdated
Show resolved
Hide resolved
|
||
For this reason, the Query Loop block supports a property called `allowedControls` which accepts an array of keys of the controls we want to whitelist. By default, we accept all the controls, but as soon as we provide an array to this property, we want to be specific and whitelist only the controls which are going to be relevant for us! | ||
|
||
As of version 13.9, the following controls are available: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we add the GB version or the WP one here ? 🤔
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a good question, I went with GB as my first draft, but it depends on what's the usual convention for the docs and if the context in which they appear makes it clear they are for GB or WP. Just let me know and I'll act accordingly.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can leave this discussion open for documentation folks to chime in. In general we will need some other small changes in some other files for the documentation to work, but we can add them in the end, when the copy is finalized.
docs/how-to-guides/block-tutorial/extending-the-query-loop-block.md
Outdated
Show resolved
Hide resolved
```js | ||
{ | ||
/** ...variation properties */ | ||
isActive: [ 'postType' ], |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just occurred to me that the shorthand version of isActive
only supports top level attributes, so the postType
which lives inside query
attribute wouldn't work.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, excellent point! Do you think we could recommend to only use namespace
or change it to a function instead? In my latest commit I changed it to a function, but happy to revert it back to an array.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think your example is good with a function because you explain very well below what the pitfall could be. Maybe we could just add a sentence in the end that most(if all times) the namespace
could be enough and that would simplify the isActive function to ['namespace']
.
Change enhables to enables Co-authored-by: Sören Wrede <[email protected]>
Specifically: * Added the complete code at the beginning * Change `isActive` from array to function * Reworded a few things * Added information about custom logic and other hints
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hello @ntsekouras and @fabiankaegy ! Thanks a lot for your insightful feedback, I am glad you found this doc valuable. I pushed a commit addressing your points, let me know how we could improve this further.
} | ||
``` | ||
|
||
Also note that the Query Loop block supports `'block'` as a string in the `scope` property, and it will allow the variation to be picked up after inserting the block itself. Read more about the Block Variation Picker [here](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And don't we want to inform users that this is possible? I find that, especially with #44197, it could be really helpful. At least, that's something we will definitely use in Woo Blocks.
```js | ||
{ | ||
/** ...variation properties */ | ||
isActive: [ 'postType' ], |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, excellent point! Do you think we could recommend to only use namespace
or change it to a function instead? In my latest commit I changed it to a function, but happy to revert it back to an array.
|
||
For this reason, the Query Loop block supports a property called `allowedControls` which accepts an array of keys of the controls we want to whitelist. By default, we accept all the controls, but as soon as we provide an array to this property, we want to be specific and whitelist only the controls which are going to be relevant for us! | ||
|
||
As of version 13.9, the following controls are available: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a good question, I went with GB as my first draft, but it depends on what's the usual convention for the docs and if the context in which they appear makes it clear they are for GB or WP. Just let me know and I'll act accordingly.
|
||
Notice that we have also disabled the `postType` control: when the user selects our variation, why show them a confusing dropdown to change the post type? On top of that it might break the block as we can implement custom controls, as we'll see shortly. | ||
|
||
### Adding additional controls |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hey @fabiankaegy, thanks for the feedback. Is the isMyBooksVariation
the only part you find confusing, or is there something else that's unclear?
In my latest commit I changed the comment above the code to this:
// We only want to add these controls if it is our variation,
// so here we can implement a custom logic to check for that, similiar
// to the `isActive` function described above.
// The following assumes that you wrote a custom `isMyBooksVariation`
// function to handle that.
Does it sound more appropriate?
I mean, I can also provide the full code for isMyBooksVariation
, but I wanted to keep the guide focused and not be too railroad-y. What do you think?
|
||
### Making your custom query work on the front-end side | ||
|
||
The Query Loop block functions mainly through the Post Template block which receives the attributes and builds the query from there. Other first-class children of the Query Loop block (such as the Pagination block) behave in the same way. They build their query and then expose the result via the filter [`query_loop_block_query_vars`](https://developer.wordpress.org/reference/hooks/query_loop_block_query_vars/). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm actually unsure of how it works, that's something I needed to clarify with you folks. I added the URL using the convention I saw, assuming that some sort of script reads the JSDoc of a hook and publishes the updated references. Would that be correct? Or who would I have to ask?
You can hook into that filter and modify your query accordingly. Just make sure you don't cause side-effects to other Query Loop blocks by at least checking that you apply the filter only to your variation! | ||
|
||
```php | ||
if( 'my-plugin/books-list' === $block[ 'attrs' ][ 'namespace' ] ) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So, this would be a bit tricky. Because I don't want to get too prescriptive in this guide and people can take their own route as preferred to access the block. We do it inside a pre-render filter. I will add some info about that, however, I understand this is a bit confusing.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for all the improvements you have made to this already very useful tutorial :) From my point of view this is ready to ship 🚀
|
||
In our case, the property would look like this: | ||
|
||
```js |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is not clear where this needs to be added. I am working through this with GB 14.1 and cannot get this part to affect the variation in anyway.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just to follow up, the key was incorrect.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think all the feedback to the copy has been addressed so far. I'd say last thing is this @ntsekouras
|
||
With the block variations API you can provide the default settings that make the most sense for your use-case. | ||
|
||
Let's go on a journey, for example, of setting up a variation that could fit a plugin which registers a `book` [custom post type](https://developer.wordpress.org/plugins/post-types/). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You're right. Maybe "suit" was a better choice than "fit". But I have changed it with "for" to keep it simple
After a conversation with @ryanwelcher and his attempt to follow this guide on his Twitch stream (links here: Previewing some REALLY cool features coming in WordPress 6.1, Follow up stream for Query Loop variations!), I've decided to add a section about the shortcomings of Why If we feel differently, I can try my hand at it. Perhaps @ntsekouras we could do something together, or maybe @ryanwelcher you could share what you have learned on your stream so we can put in doc format. How do you feel? Personally, I think we should not add much more to this guide specifically, but we can add another file (either in this PR or a separate PR) and then link it. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(duplicate, ignore this)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm excited to use these and this documentation provides some clear guidance on using these variations.
I've requested a couple improvements to improve accessibility.
|
||
## Extending the block with variations | ||
|
||
By registering your own block variation with some specific Query Loop block settings, you can have finer control over how it is presented, while still being able to use the full capabilities which the Query Loop block offers underneath. If you are not familiar with block variations, learn more about them [here](/docs/reference-guides/block-api/block-variations.md). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If you are not familiar, learn more about [block variations](/docs/reference-guides/block-api/block-variations.md).
|
||
### Customize your variation layout | ||
|
||
Please note that the Query Loop block supports `'block'` as a string in the `scope` property. In theory, that's to allow the variation to be picked up after inserting the block itself. Read more about the Block Variation Picker [here](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Another improved link . linking the descriptive term provides better context for users who browse the document by the links.
Read more about the [Block Variation Picker](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a subtle mistake that slipped through the original PR about allowedControls
key and I have a PR that changes that. I think it's safe to rename as the original PR landed just two weeks ago.
I think we can land this for now and I'll create a follow up for any additions/changes, and most importantly include some doc related changes in manifest
files, etc.. I'll also see to handle the remaining feedback in this PR.
Thanks so much everyone for the feedback and @sunyatasattva for the writeup 💯
docs/how-to-guides/block-tutorial/extending-the-query-loop-block.md
Outdated
Show resolved
Hide resolved
docs/how-to-guides/block-tutorial/extending-the-query-loop-block.md
Outdated
Show resolved
Hide resolved
I'm sorry if it's wrong place to clarify. I've read official docs and tried to add custom query param as descibed here
but it has no ny effect on query block variation. Query always outputs with the same amount of query params:
would be great to add to docs clarification how to add custom param (bookAuthor in this case in docs) to query block variation. I've tried all possible approaches - no one worked. I don't see how it's possible to add custom param to query. |
What?
This PR adds extensive details and explains how to make best use of the changes to the Query Loop block introduced in the following PRs: #43590, #43632 and #44093.
Why?
The changes introduced above allow for powerful custamizability of the Query Loop block, but are also quite hidden and their usage can be a bit esoteric. This documentation aims to create a step-by-step tutorial on how to effectively implement all those changes.
How?
Adding a documentation page detailing how to extend the Query Loop block.
Testing Instructions
n/a
Screenshots or screencast
n/a
Note
While I think the documentation itself is quite complete, I suppose it needs to be linked from somewhere or added to the generated table of contents. Happy to have guidance on that part.