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

Add docs for extending the Query Loop block via variations #44137

Merged

Conversation

sunyatasattva
Copy link
Contributor

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.

Detail and explain how to make best use of the changes introduced in
the following PRs: WordPress#43590, WordPress#43632 and WordPress#44093
Copy link
Member

@fabiankaegy fabiankaegy left a 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
Copy link
Member

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.

Copy link
Contributor Author

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' ] ) {
Copy link
Member

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?

Copy link
Contributor Author

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/).
Copy link
Member

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?

Copy link
Contributor Author

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?

@fabiankaegy fabiankaegy added [Type] Developer Documentation Documentation for developers [Block] Query Loop Affects the Query Loop Block labels Sep 14, 2022
Copy link
Contributor

@ntsekouras ntsekouras left a 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/).
Copy link
Contributor

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.

Copy link
Contributor Author

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!

Copy link
Contributor

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.

Copy link
Contributor Author

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', {
Copy link
Contributor

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.

Copy link
Contributor

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).
Copy link
Contributor

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.

Copy link
Contributor Author

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.

Copy link
Contributor

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.


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:
Copy link
Contributor

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 ? 🤔

Copy link
Contributor Author

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.

Copy link
Contributor

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.

@ntsekouras ntsekouras mentioned this pull request Sep 16, 2022
89 tasks
```js
{
/** ...variation properties */
isActive: [ 'postType' ],
Copy link
Contributor

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.

Copy link
Contributor Author

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.

Copy link
Contributor

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'].

sunyatasattva and others added 2 commits September 16, 2022 17:04
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
Copy link
Contributor Author

@sunyatasattva sunyatasattva left a 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).
Copy link
Contributor Author

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' ],
Copy link
Contributor Author

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:
Copy link
Contributor Author

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
Copy link
Contributor Author

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/).
Copy link
Contributor Author

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' ] ) {
Copy link
Contributor Author

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.

Copy link
Member

@fabiankaegy fabiankaegy left a 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
Copy link
Contributor

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.

Copy link
Contributor

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.

Copy link
Contributor Author

@sunyatasattva sunyatasattva left a 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/).
Copy link
Contributor Author

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

@sunyatasattva sunyatasattva requested review from ryanwelcher and removed request for ntsekouras and Soean September 22, 2022 14:18
@sunyatasattva
Copy link
Contributor Author

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 scope: [ 'block' ] and why it shouldn't be used.

Why innerBlocks should be used instead, and, after #44197, variation-specific patterns. My latest commit adds only a mention of that. I didn't have enough time and familiarity to test and play around with those to write more about that yet. However, I also feel the guide might be getting long and we want to get people up and running: variation-specific patterns could be a topic for another guide.

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.

Copy link
Member

@skorasaurus skorasaurus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(duplicate, ignore this)

Copy link
Member

@skorasaurus skorasaurus left a 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).
Copy link
Member

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).
Copy link
Member

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).

Copy link
Contributor

@ntsekouras ntsekouras left a 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 💯

@chyvak1831
Copy link

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

https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/extending-the-query-loop-block/

{
    /** ...variation properties */
    attributes: {
        /** ...variation attributes */
        query: {
            /** ...more query settings if needed */
            postType: 'book',
            /** Our custom query parameter */
            bookAuthor: 'J. R. R. Tolkien'
        }
    }
}

but it has no ny effect on query block variation. Query always outputs with the same amount of query params:

{"queryId":2,"query":{"perPage":3,"pages":0,"offset":0,"postType":"brand","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":false},"namespace":"featured-posts-query-variation"}

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Block] Query Loop Affects the Query Loop Block [Type] Developer Documentation Documentation for developers
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants