Add menu_order sorting option to Query Loop block #68781

kasparsd · 2025-01-20T09:55:47Z

What?

Add the menu_order sorting option in addition to post title and date.

Why?

Users are able to set a numerical menu order for post types that support it (pages, by default). Smaller values rise to the top while larger values sink to the bottom, as implemented by WP_Query ordering.

How?

Extend the QueryControls component to include menu_order as one of the options.
Add "Menu order descending" and "Menu order ascending" options to the order selector.

Questions

While the menu_order value is available for all post types in the database, only those that register support for page-attributes feature will have the setting available. What's the best approach to including the menu_order option only to post types with the page attributes enabled? Here is how the "Order" gets added conditionally to the dataviews:

gutenberg/packages/editor/src/dataviews/store/private-actions.ts

Lines 156 to 158 in be5ce8a

    
           postTypeConfig.supports?.[ 'page-attributes' ] 
        
           	? reorderPage 
        
           	: undefined,

Testing Instructions

Create multiple pages.
Set custom menu order values for each of the pages either in the page list (under Quick Edit) or via page settings which are hard to find (three dots menu).
Create a new page and include a Query Loop block.
Select pages post type and order by "Menu order".
Confirm that the query loop output is rendering the posts in the expected order.

Testing Instructions for Keyboard

This change is extending an existing selector so the keyboard navigation remains unchanged.

Screenshots or screencast

Before	After

Ordering examples with updated preview:

Descending:

Ascending:

github-actions · 2025-01-20T09:56:01Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: kasparsd <[email protected]>
Co-authored-by: carolinan <[email protected]>
Co-authored-by: Mamaduka <[email protected]>
Co-authored-by: karmatosed <[email protected]>
Co-authored-by: Humanify-nl <[email protected]>
Co-authored-by: mikeritter <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

kasparsd · 2025-01-20T09:58:10Z

packages/components/src/query-controls/index.tsx

@@ -75,6 +75,37 @@ export function QueryControls( {
 	// but instead are destructured inline where necessary.
 	...props
 }: QueryControlsProps ) {
+	const orderByList = [


The name here matches the props.categoriesList convention used below with orderBy being the feature.

packages/block-library/src/query/edit/inspector-controls/order-control.js

carolinan · 2025-01-20T12:02:56Z

Thank you for working on this.
I understand that the menu order is the correct technical name, but it may be confusing for users, is there a better label for the select, that will make it easy to use for both developers and users?

In the block editor when you edit a page and change the order, the label for the option is just "Order", but "Order by order" is not a helpful label 😆

kasparsd · 2025-01-20T12:06:26Z

Thank you for reviewing the changeset @carolinan!

but "Order by order" is not a helpful label

Right!? That is why I left it at "menu order" because I couldn't think of a better term that would work equally well between various post types. How about "Sort by manual order" or "Sort by custom order"?

karmatosed · 2025-01-20T17:40:36Z

First, kudos for working on this, @kasparsd. Second, while the dropdown is totally native, I did wonder about bringing the same filtering now in from DataViews and the documentation in Storybook here. I don't want to derail this ticket though. Let's ship good things quickly. I will make another one as I feel some unification can be done. Beyond that, thank you again; it's so great to see.

kasparsd · 2025-01-20T17:47:17Z

Thank you @karmatosed for reviewing the ticket and providing the additional context!

I feel some unification can be done

I had the exact same feeling when I saw the ordering options repeated in three different places across the codebase. It feels like there must be some historic context that would explain that and potentially an existing initiative that is working to resolve this.

So I'm openly asking for support for (1) how to bring in the contextual availability for the menu_order option, and (2) how to name the actual option because "order by order" doesn't sound great and "menu order" isn't used anywhere in the UI.

carolinan · 2025-01-21T04:00:57Z

It also can't use "Page order" since it can be enabled on other post types.
"manual order" sounds like I should be able to drag and drop the items to a completely custom order.

karmatosed · 2025-01-21T11:41:46Z

I had the exact same feeling when I saw the ordering options repeated in three different places across the codebase. It feels like there must be some historic context that would explain that and potentially an existing initiative that is working to resolve this.

My thinking was a different issue to solve that but happy to bring it to this. What I wanted was to get this one in. Let's do a quick audit of where and how are close to it for now. I am picking where order is set to allow a comparison and also showing the context:

Using dropdown component as you have.
Using popover show menu as posts do. Posts have a two-step which I am not fond of if honest. You select menu, show popover then also a modal appears on 'order'. We probably don't want that pattern here.

I am very reluctant to bring in another popover here as in this query interface they seem to be used primarily to expose hidden menus, this isn't the right place for that.

To recap what we see today in that section:

A possible idea would be to even consider if 'order by' should be in toolbar. I am slightly against this because I have seen many agencies extend this section. This is why I don't want to just add icons here either.

My recommendation

For now, stick with dropdown.
Revisit this area and others in another ticket.
Add the words 'Ascending by menu' or 'Descending by menu'. To align with language shared where order happens in modal, this probably could be 'Ascending by order' and 'Descending by order'.

My suggestion comes based on the current word patterns but it would be great to check those based on translations.

kasparsd · 2025-01-21T13:06:57Z

Thanks for the additional context @karmatosed! I've updated the labels per your recommendation. I believe this is the best we can do without revisiting the whole "menu order" label across the admin (quick edit, page order configuration, etc.).

carolinan · 2025-02-17T11:30:46Z

Duplicate: #51290

kasparsd · 2025-02-17T11:36:23Z

Thanks for finding the prior attempts at this @carolinan! I've responded inline #51290 with the requirements for the custom order availability.

packages/block-library/src/query/edit/inspector-controls/order-control.js

packages/block-library/src/query/utils.js

packages/components/src/query-controls/types.ts

kasparsd · 2025-02-17T13:27:55Z

I've updated the changeset to dynamically resolve the supported orderBy options based on a post type.

Here is the list of ordering options for posts (which don't support custom menu_order):

And a list of ordering options for pages which do support custom menu_order:

packages/components/src/query-controls/README.md

Mamaduka · 2025-02-26T15:09:22Z

@kasparsd, I left some notes, but generally, this looks good.

Note: If we want to ship this with WP 6.8, PR should be ready and merged before the next Gutenberg RC release on Friday. @kasparsd, do you have time to follow up on the remaining items?

…-option

kasparsd · 2025-02-28T08:59:05Z

packages/block-library/src/query/edit/inspector-controls/order-control.js

+function OrderControl( {
+	order,
+	orderBy,
+	orderByOptions = defaultOrderByOptions,


We're keeping the defaults as fallback to prevent breaking changes.

packages/block-library/src/query/utils.js

kasparsd · 2025-02-28T09:07:02Z

packages/components/src/query-controls/README.md

 };

 const MyQueryControls = () => {
 	const [ query, setQuery ] = useState( QUERY_DEFAULTS );
-	const { category, categories, maxItems, minItems, numberOfItems, order, orderBy  } = query;
+	const { category, categories, maxItems, minItems, numberOfItems, order, orderBy } = query;


@Mamaduka I got confused by the use of categories here. Technically that is also not part of the query coming from block attributes. How do you suggest we represent the orderByOptions here, if at all?

…r sorting so we don’t attempt to resolve it

kasparsd

Thanks for your review and feedback @Mamaduka! I've addressed all of your feedback. Please let me know if you have any additional questions or suggestions.

kasparsd added 4 commits January 20, 2025 10:45

Add support for menu order

f0c3039

Add the menu order option

11fca2e

Two more copy-paste location

681186c

Match the order

27dd5a1

kasparsd requested a review from ajitbohra as a code owner January 20, 2025 09:55

kasparsd requested a review from fabiankaegy as a code owner January 20, 2025 09:56

carolinan added [Type] Enhancement A suggestion for improvement. [Block] Query Loop Affects the Query Loop Block labels Jan 20, 2025

kasparsd commented Jan 20, 2025

View reviewed changes

packages/block-library/src/query/edit/inspector-controls/order-control.js Outdated Show resolved Hide resolved

Update labels per discussion

a50362f

kasparsd added 9 commits February 17, 2025 14:15

Helper for resolving order by options for a post type

6def53a

Add the option type

0ed2ac0

Pass in the options

066e3e3

Restrict the values to only known values

f40d2b6

Keep the order

777debf

Define the type for just the option

ba52675

Document the updated fields

016c83e

Update the examples

568fd9d

Reference the type

f6af1ec

This is really required for the drop-down component, keep it simple here

27a3c60

kasparsd commented Feb 17, 2025

View reviewed changes

packages/block-library/src/query/edit/inspector-controls/order-control.js Outdated Show resolved Hide resolved

packages/block-library/src/query/utils.js Show resolved Hide resolved

packages/components/src/query-controls/types.ts Outdated Show resolved Hide resolved

Mamaduka reviewed Feb 26, 2025

View reviewed changes

packages/components/src/query-controls/README.md Outdated Show resolved Hide resolved

kasparsd added 8 commits February 28, 2025 10:29

Merge remote-tracking branch 'origin/trunk' into 42710-add-menu-order…

ef44e18

…-option

Add back the default options to prevent breaking changes

a6c408a

Use memo to avoid rebuilding the list of options

49affb3

Add back the defaults to avoid breaking changes

1becd19

Keep the default as prefix to match the rest of coding style

27c04ea

Rely on the default orderby options for now

924364c

Remove for now

2cca836

Resolve the options via the helper instead

d7e34aa

kasparsd commented Feb 28, 2025

View reviewed changes

Latest posts list only posts which don’t support custom menu order fo…

ca99bbd

…r sorting so we don’t attempt to resolve it

kasparsd commented Feb 28, 2025

View reviewed changes

kasparsd added 3 commits February 28, 2025 11:50

Add our changelog

3947b6a

Formatting

7cc05e8

Document the change

4c6a316

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add menu_order sorting option to Query Loop block #68781

Add menu_order sorting option to Query Loop block #68781

kasparsd commented Jan 20, 2025 •

edited

Loading

github-actions bot commented Jan 20, 2025 •

edited

Loading

kasparsd Jan 20, 2025

carolinan commented Jan 20, 2025

kasparsd commented Jan 20, 2025

karmatosed commented Jan 20, 2025

kasparsd commented Jan 20, 2025 •

edited

Loading

carolinan commented Jan 21, 2025 •

edited

Loading

karmatosed commented Jan 21, 2025 •

edited

Loading

kasparsd commented Jan 21, 2025

carolinan commented Feb 17, 2025

kasparsd commented Feb 17, 2025

kasparsd commented Feb 17, 2025

Mamaduka commented Feb 26, 2025

kasparsd Feb 28, 2025

kasparsd Feb 28, 2025

kasparsd left a comment

	postTypeConfig.supports?.[ 'page-attributes' ]
	? reorderPage
	: undefined,

Add menu_order sorting option to Query Loop block #68781

Are you sure you want to change the base?

Add menu_order sorting option to Query Loop block #68781

Conversation

kasparsd commented Jan 20, 2025 • edited Loading

What?

Why?

How?

Questions

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

github-actions bot commented Jan 20, 2025 • edited Loading

kasparsd Jan 20, 2025

Choose a reason for hiding this comment

carolinan commented Jan 20, 2025

kasparsd commented Jan 20, 2025

karmatosed commented Jan 20, 2025

kasparsd commented Jan 20, 2025 • edited Loading

carolinan commented Jan 21, 2025 • edited Loading

karmatosed commented Jan 21, 2025 • edited Loading

My recommendation

kasparsd commented Jan 21, 2025

carolinan commented Feb 17, 2025

kasparsd commented Feb 17, 2025

kasparsd commented Feb 17, 2025

Mamaduka commented Feb 26, 2025

kasparsd Feb 28, 2025

Choose a reason for hiding this comment

kasparsd Feb 28, 2025

Choose a reason for hiding this comment

kasparsd left a comment

Choose a reason for hiding this comment

kasparsd commented Jan 20, 2025 •

edited

Loading

github-actions bot commented Jan 20, 2025 •

edited

Loading

kasparsd commented Jan 20, 2025 •

edited

Loading

carolinan commented Jan 21, 2025 •

edited

Loading

karmatosed commented Jan 21, 2025 •

edited

Loading