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

kasparsd · 2025-01-20T10:16:23Z

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

@@ -23,6 +23,16 @@ const orderOptions = [
 		label: __( 'Z → A' ),
 		value: 'title/desc',
 	},
+	{


These options should be available only to post types that support page attributes. Where and how do we add that logic? Here is a reference to how the "order" setting is decided at the page settings three-dots:

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

Lines 156 to 158 in be5ce8a

postTypeConfig.supports?.[ 'page-attributes' ]

? reorderPage

: undefined,

I don't know if it helps but there is a PageAttributesCheck, that you can take inspiration from:
https://github.com/WordPress/gutenberg/blob/trunk/packages/editor/src/components/page-attributes/check.js
A check for the post type support should probably go in the block's utils.js file.

I believe this is the only remaining task before this can be merged.

Indeed! We need a decision on which post context information will be passed to this component in order for it to limit the available sorting options to what is supported by the post type (include the menu_order only if the post type supports that).

Based on my current understanding, I would recommend passing the postType data getPostType(). This would follow the existing convention of selected categories being passed to the component instead of the component attempting to resolve it from the global state.

Alternatively, we could also pass in the sorting options and the caller would be responsible for generating them based the current state.

Can usePostTypes not be updated for this purpose? https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/query/utils.js#L101

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.

kasparsd · 2025-02-17T13:13:53Z

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

-	},
-];
-function OrderControl( { order, orderBy, onChange } ) {
+function OrderControl( { order, orderBy, orderByOptions, onChange } ) {


We keep this component decoupled from any editor state and expect to receive the orderByOptions from the user similar to the order and orderBy.

Question: Is this a breaking change and should we consider an upgrade path for anyone using this component? Now, without the orderByOptions value it will render an empty selector.

kasparsd · 2025-02-17T13:15:54Z

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

+ * @param {string} postType The post type to check.
+ * @return {OrderByOption[]} List of order options.
+ */
+export function useOrderByOptions( postType ) {


This is a new helper method that returns all of the ordering options for a post type, accounting for the page-attributes support.

kasparsd · 2025-02-17T13:18:14Z

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

@@ -45,7 +45,17 @@ export type AuthorSelectProps = Pick<
 };

 type Order = 'asc' | 'desc';
-type OrderBy = 'date' | 'title';
+type OrderBy = 'date' | 'title' | 'menu_order';
+type OrderByOption = {


Does this type definition match the project conventions?

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:

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

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

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

kasparsd Jan 20, 2025

carolinan Jan 20, 2025 •

edited

Loading

carolinan Feb 17, 2025

kasparsd Feb 17, 2025

carolinan Feb 17, 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 Feb 17, 2025

kasparsd Feb 17, 2025

kasparsd Feb 17, 2025

kasparsd commented Feb 17, 2025

	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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carolinan Jan 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kasparsd commented Feb 17, 2025

kasparsd commented Jan 20, 2025 •

edited

Loading

github-actions bot commented Jan 20, 2025 •

edited

Loading

carolinan 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