New block: Query filter

[ryelle]

See #419 — this adds a new block called "Query Filter", which renders a dropdown form using values passed in via filter. When "Apply" is clicked, the form is submitted, and the resulting URL is expected to handle the applied filters. In many cases, wp_query can handle combined filters without any customization (ex, taxonomies). For non-core filters, hooking into pre_get_posts (+ maybe query_vars?) in the child theme should be enough.

This block is using the Interactivity API, which uses data-wp- attributes to attach events and conditional attributes. This API is still experimental, but I took a lot of inspiration from the navigation block.

By itself, this block doesn't render anything. It expects a key attribute, which is used to create a specific filter for the individual sites to populate a settings object. For example, the following would be used to create an "example" filter.

<!-- wp:group {"layout":{"type":"flex","flexWrap":"nowrap","justifyContent":"right"}} -->
<div class="wp-block-group">
    <!-- wp:wporg/query-filter {"key":"example"} /-->
</div>
<!-- /wp:group -->

This creates the WP filter hook wporg_query_filter_options_example, which expects an object used to render the options. There's more documentation inline in render.php.

To create a simple dropdown with 3 options:

add_filter(
	'wporg_query_filter_options_example',
	function() {
		return array(
			'label' => 'Example <span>1</span>',
			'key' => 'q',
			'action' => home_url(),
			'options' => array(
				'opt-1' => 'Option 1',
				'opt-2' => 'Option 2',
				'opt-3' => 'Option 3',
			),
			'selected' => array( 'opt-2' ),
		);
	}
);

The output would look like this:

When "Apply" is clicked, the page loads /?q[]=opt-2. It's up to each site to load the correct archive.

❓ I think this approach will work well for the child theme setup, but I definitely want feedback on it before committing us all to this for all the directories 🙂

🖌️ I've also used block-specific custom properties so that other themes can easily change colors with theme.json changes (here's an example in showcase, though i removed it once everything was set up since the defaults work). This is in case the theme directory needs a dark scheme.

Practical example: Showcase

I've got this working with real filters in WordPress/wporg-showcase-2022#147 — here are some screen recordings of everything in place:

A basic filtering, starting on the homepage, shows all 3 filters & options. When a filter is applied, the results load using the archive template.

basic-demo.mp4

More filtering interactions — clearing filters using "Clear" and by clicking the option; applying multiple filters, clicking out before applying.

more-demo.mp4

Search and filters can work together — once on a search results page, filtering will filter the search results. (the opposite is not true, if you search on a filtered page it will remove the filters, we talked through that and it was expected behavior)

search-demo.mp4

When clicking on a tag archive page, the filter for that tag is correctly selected.

tag-demo.mp4

And on mobile, the dropdown switches to a modal

[StevenDufresne]

I think it was agreed that this would be updated with the filter count:

Context Link
Figma Link

Image

[ryelle]

I've been only referencing the "filters 6.1" page in the Filter component file, thinking that was the final version 🙃

The link doesn't work for me (opens the file but wrong page)… but I found it by searching through the other pages, so thanks for pointing it out.

@WordPress/meta-design — Can you confirm how this should behave? It sounds like the top number (on black, red highlight) would be the number of filters currently applied on the page, while the Apply button (on blue, yellow highlight) would be the number of filters currently selected— so it would stay "Popular tags 1" even if you select two more, but the button would be "Apply (3)"?

[jasmussen]

It sounds like the top number (on black, red highlight) would be the number of filters currently applied on the page, while the Apply button (on blue, yellow highlight) would be the number of filters currently selected— so it would stay "Popular tags 1" even if you select two more, but the button would be "Apply (3)"?

Correct, but honestly I think we can remove the number on the Apply button for now, I'm not sure it adds clarity. If Francisco when he comes back from AFK has to correct me, I will buy him an apology milkshake at that time. How does this sound?

[ryelle]

I think it was an accessibility request, but maybe it would be easier to understand the UX once this is merged and live on the staging site. I'll leave this as-is (no number on button) for this initial pass, and ask for feedback once there's a live place to try it out.

[fcoveram]

@ryelle is correct. It was an accessibility request shared here.

[StevenDufresne]

I tested it locally, and while I don't yet have the expertise to review the interactivity implementation, it does work well and updates the query string appropriately. 👍

[ryelle]

@WordPress/meta-design I meant to flag this in the description— the mockup uses "Pomegrade" on white but that fails to meet contrast requirements. There's a note in the design library about darker versions of colors, but I didn't see any, so I've made this one up. If you'd rather something different, it just needs to have a 4.5+ value against light-grey-2, since I'm using that as the hover color.

Hover: