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.

Sign up for GitHub

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

Feat : Improve Docs for useNavigationMenu hook #68499

Open
wants to merge 1 commit into
base: trunk
Choose a base branch
from
Open

Feat : Improve Docs for useNavigationMenu hook #68499

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 48 additions & 15 deletions packages/block-library/src/navigation/use-navigation-menu.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,38 @@ import { useSelect } from '@wordpress/data';
*/
import { PRELOADED_NAVIGATION_MENUS_QUERY } from './constants';

/**
* Retrieves comprehensive information about a navigation menu and related permissions.
*
* This hook provides a centralized way to access navigation menu data, user permissions,
* and related states. It's particularly useful for components that need to render or
* manage navigation menus in the WordPress block editor or related interfaces.
*
* @param {number|undefined} ref The post ID of the navigation menu. If undefined, some
* return values will be affected (see return object for details).
*
* @return {Object} An object containing navigation menu data and related states:
* - navigationMenu: The navigation menu post object if it exists and is published or draft, null otherwise.
* - isNavigationMenuResolved: Whether the navigation menu data has finished loading.
* - isNavigationMenuMissing: Whether the specified navigation menu doesn't exist or isn't accessible.
* - navigationMenus: An array of all available navigation menu objects.
* - isResolvingNavigationMenus: Whether the list of navigation menus is still loading.
* - hasResolvedNavigationMenus: Whether the list of navigation menus has finished loading.
* - canSwitchNavigationMenu: Whether there are multiple menus available to switch between.
* - canUserCreateNavigationMenus: Whether the current user has permission to create new navigation menus.
* - isResolvingCanUserCreateNavigationMenus: Whether the create permission is still being checked.
* - hasResolvedCanUserCreateNavigationMenus: Whether the create permission check has completed.
* - canUserUpdateNavigationMenu: Whether the user can update the specified menu. Undefined if no ref provided.
* - hasResolvedCanUserUpdateNavigationMenu: Whether the update permission check has completed. Undefined if no ref provided.
* - canUserDeleteNavigationMenu: Whether the user can delete the specified menu. Undefined if no ref provided.
* - hasResolvedCanUserDeleteNavigationMenu: Whether the delete permission check has completed. Undefined if no ref provided.
*/
export default function useNavigationMenu( ref ) {
// Retrieve permissions related to CRUD operations for Navigation Menus.
const permissions = useResourcePermissions( {
kind: 'postType',
name: 'wp_navigation',
id: ref,
id: ref, // Necessary to retrieve update and delete permissions. Defaults to true if not provided.
} );

const {
Expand All @@ -32,14 +59,9 @@ export default function useNavigationMenu( ref ) {
);

const {
// Can the user create navigation menus?
canCreate: canCreateNavigationMenus,

// Can the user update the specific navigation menu with the given post ID?
canUpdate: canUpdateNavigationMenu,

// Can the user delete the specific navigation menu with the given post ID?
canDelete: canDeleteNavigationMenu,
canUpdate: canUpdateNavigationMenu, // undefined if ref is missing.
canDelete: canDeleteNavigationMenu, // undefined if ref is missing.
isResolving: isResolvingPermissions,
hasResolved: hasResolvedPermissions,
} = permissions;
Expand Down Expand Up @@ -80,6 +102,21 @@ export default function useNavigationMenu( ref ) {
};
}

/**
* Selects and retrieves information about an existing navigation menu.
*
* This function uses the WordPress data layer to fetch information about a specific
* navigation menu. It handles both published and draft navigation menus, which is
* particularly useful in the context of the block editor where draft posts are valid.
*
* @param {Function} select The `select` function from the WordPress data store.
* @param {number|undefined} ref The ID of the navigation menu to select.
*
* @return {Object} An object containing information about the navigation menu:
* - isNavigationMenuResolved: Whether the data for the navigation menu has finished loading.
* - isNavigationMenuMissing: Whether the requested navigation menu doesn't exist or isn't accessible.
* - navigationMenu: The navigation menu object if it exists and is published or draft, null otherwise.
*/
function selectExistingMenu( select, ref ) {
if ( ! ref ) {
return {
Expand All @@ -99,10 +136,9 @@ function selectExistingMenu( select, ref ) {
args
);

// Only published Navigation posts are considered valid.
// Draft Navigation posts are valid only on the editor,
// requiring a post update to publish to show in frontend.
// To achieve that, index.php must reflect this validation only for published.
// Only published and draft Navigation posts are considered valid.
// Draft Navigation posts are valid only in the editor context,
// requiring a post update to publish to show in the frontend.
const isNavigationMenuPublishedOrDraft =
editedNavigationMenu.status === 'publish' ||
editedNavigationMenu.status === 'draft';
Expand All @@ -112,9 +148,6 @@ function selectExistingMenu( select, ref ) {
isNavigationMenuMissing:
hasResolvedNavigationMenu &&
( ! navigationMenu || ! isNavigationMenuPublishedOrDraft ),

// getEditedEntityRecord will return the post regardless of status.
// Therefore if the found post is not published then we should ignore it.
navigationMenu: isNavigationMenuPublishedOrDraft
? editedNavigationMenu
: null,
Expand Down
Loading