CPT Submenu Items in ACF Pro Options Admin Menu

This Pro tutorial provides the steps to add links to

• a taxonomy terms
• a custom post type’s “Add New”
• a custom post type’s listing

admin pages under an Options page created with ACF Pro.

All code mentioned in this tutorial is to be added in the child theme’s functions.php or a code snippets plugin.

Step 1

Let’s create an ACF Options page by adding:

// Add ACF Options page.
if ( function_exists( 'acf_add_options_page' ) ) {
	$options = [
		'page_title' => __( 'Site Options' ),
		'position' => '2.38856', // as 3rd item
		'menu_slug' => 'site-options', // if left empty, ACF will use the page title slug but prefixes it with acf-options-.
	];

	acf_add_options_page( $options );
}

To add fields in this options page, go to Custom Fields → Add New and create a new field group. For the location, select “Site Options”.

Step 2

Add the ACF Options page as a submenu. This will be the first submenu item.

// Add ACF Options page as a submenu.
add_submenu_page( 'site-options', 'Site Options', 'Site Options', 'manage_options', 'site-options' );

The 1st argument in the add_submenu_page function is the slug name for the parent menu.

The 2nd argument is text to be displayed in the page’s title tags when the menu is selected.

The 3rd argument is text to be used for the menu.

The last argument we are passing is the slug name to refer to this menu. Since we want to add a link to the options page, we are using the menu slug from the previous step.

Step 3

Next add

add_submenu_page( 'site-options', 'Project Categories', 'Project Categories', 'manage_options', 'edit-tags.php?taxonomy=project_category&post_type=project' );

add_submenu_page( 'site-options', 'Add New Project', 'Add New Project', 'manage_options', 'post-new.php?post_type=project' );

Replace

a) Project Categories text with your taxonomy title.

b) project_category with your taxonomy name/identifier.

c) project with your CPT name/identifier.

d) Add New Project with your desired text.

Make similar changes where applicable in the subsequent steps.

If you want the “All Projects” menu item (to be added later) to appear above, like this:

change the above code to:

add_action( 'admin_menu', function() {
	add_submenu_page( 'site-options', 'Project Categories', 'Project Categories', 'manage_options', 'edit-tags.php?taxonomy=project_category&post_type=project' );

	add_submenu_page( 'site-options', 'Add New Project', 'Add New Project', 'manage_options', 'post-new.php?post_type=project' );
});

Step 4

If you click on the link to the taxonomy list screen, you’ll see that it appears on its own and not as a submenu of the Site Options menu item.

Add this to fix:

// Set `site-options` as the parent menu item for the Project Category taxonomy.
// If this is not done, the Project Category taxonomy will appear without a parent menu.
add_action( 'parent_file', function( $parent_file ) {
	if ( get_current_screen()->taxonomy === 'project_category' ) {
		return 'site-options';
	}

	return $parent_file;
});

Now, there’s another challenge to tackle – the “Project Categories” submenu item is not bolded and is not in white color meaning it is not highlighted.

To fix this, add:

// Make Project Category the active menu item when editing a Service Type.
add_action( 'admin_head-edit-tags.php', function() {
	if ( get_current_screen()->taxonomy === 'project_category' ) { ?>
		<script type="text/javascript">
			// Locate the anchor tag that links to the project_category taxonomy admin page and add a class of "current" to its parent list item.
			document.addEventListener( 'DOMContentLoaded', function() {
				const projectCategoriesLink = document.querySelector( 'a[href="edit-tags.php?taxonomy=project_category&post_type=project"]' );

				if ( projectCategoriesLink ) {
					const projectCategoriesLinkParent = projectCategoriesLink.parentNode;
					projectCategoriesLinkParent.classList.add( 'current' );
				}
			} );

		</script>
	<?php }
});

Step 5

To add a link to add a new project as a submenu item of our Site Options admin menu, go to where your CPT has been configured, for example, by editing that post type in CPT UI settings.

Set site-options as the top-level admin menu page.

We need to fix the lack of highlight issue.

Add:

add_action( 'admin_head-post-new.php', function() {
	if ( get_current_screen()->base === 'post' && get_current_screen()->post_type === 'project' ) { ?>
		<script type="text/javascript">
			document.addEventListener( 'DOMContentLoaded', function() {
				// Remove current class from li.wp-first-item
				const wpFirstItem = document.querySelector( '#toplevel_page_site-options li.wp-first-item' );
				if ( wpFirstItem) {
					wpFirstItem.classList.remove( 'current' );
				}

				// Locate the anchor tag that links to the Add New Project admin page and add a class of "current" to its parent list item.
				const addNewProjectLink = document.querySelector( 'a[href="post-new.php?post_type=project"]' );

				if ( addNewProjectLink ) {
					const addNewProjectLinkParent = addNewProjectLink.parentNode;
				 	addNewProjectLinkParent.classList.add( 'current' );
				}
			} );

		</script>
	<?php }
});

References

add taxonomy admin page as a submenu WordPress – Google Search

WordPress custom taxonomy link not highlighted under custom admin menu – Stack Overflow

ACF | acf_add_options_page()

add_submenu_page() | Function | WordPress Developer Resources