Altering WordPress Admin Menus

Over the last few months I have worked on a number of projects that have required some modifications to the WordPress admin screens. Sometimes it was just to make things easier for the client and others I needed to add different menus and admin pages for various reasons. One task I undertook required me to move WordPress admin menus around, and have them display under different top level menus. Here is how I managed to add, remove and edit the WordPress menus.

WordPress core provides us with a lot of tools and functions for editing both the WordPress admin and the WordPress admin menu items.

Adding Top Level Menu Items

The WordPress admin menu is two-tiered. By that, I mean there can be two levels of menu items. Top level menus such as Appearance can have sub level menus beneath them such as Widgets. You can add top level menus really easily by using the following code in your own plugin (or theme functions file but I would not recommend that).

https://gist.github.com/wpmark/5f300ad2724163c3ef1a

You will see the function takes 6 arguments which are needed. Lets take a look at what these are:

1. Page title – this is the text that is added to the pages <title> tags in the head of the page
2. Menu title – this is the label given to the menu in the WordPress admin. This is what the user sees in the admin.
3. Capability – this sets what capability a user needs in order to be able to see and have access to this menu
4. Menu slug – this is a unique slug to which this menu items if referenced by
5. Callback function – the callback function is the function used to output the pages content once the menu item is clicked
6. Icon – this is the icon that displays next to the menu title. You can pass a dashicon string here or pass div which can then be styled with an admin stylesheet.
7. Position – this sets where your menu items will appear in the list of menu items. Take a look here for what the position of each core menu is

Notice how the function we build, which includes the call to add_menu_page() is added to WordPress using the admin_menu action hook.

This code will now add your menu to WordPress. However when you click on your menu you will get an error. The reason for this is that WordPress is trying to find a function with the name we gave to the callback arg in the function, in order to display the pages content. However we have yet to create this.

The next step then is to create this callback function which would be something like this. Obviously you would add your pages content to this function depending on what you wanted to output.

https://gist.github.com/wpmark/ab441a40f88ab1b17297

Adding Sub Level Menu Items

We call also add a menu as a child of another menu. This is handy for adding plugin settings and the like as you would and probably should be adding this under the Settings or Tools menus. The code below would enable you to add a sub menu under tools.

https://gist.github.com/wpmark/4daeaf9142013d2e6334

Again this function takes 6 arguments so lets take a look at what these are:

1. Parent Slug – this is the menu slug of the parent item you wish to add your submenu item to. Here we use tools.php to have it display on the tools menu. We could also use a slug that we previously declared in our function above, to have our sub menu item display under a top level menu we created.
2. Page Title – this is the text that is added to the pages <title> tags in the head of the page
3. Menu Title – this is the label given to the menu in the WordPress admin. This is what the user sees in the admin.
4. Capability –  this sets what capability a user needs in order to be able to see and have access to this menu
5. Menu Slug – this is a unique slug to which this menu items if referenced by
6. Callback Function – he callback function is the function used to output the pages content once the menu item is clicked

The callback function works in the same way as for adding a top level menu.

Moving Existing WordPress Menu Items

As part of the work I was doing it required moving top level menus underneath other top level menus to make them a sub menu item. This can be done it two parts. The first part is to remove the original top level menu from the WordPress admin menu and the second is to add it in again as a sub menu item.

Lets start be removing the top level menu item for Posts.

https://gist.github.com/wpmark/bb172f9b6aad56bfa10e

The only argument passed to the remove_menu_page() function is the slug of the top level page you want to remove. Passing edit.php removes the posts item.

Now we have removed the posts menu item we want to add it back in as a sub menu of our top level menu we added above. If you remember the slug we gave to this menu item was wpmark_admin_menu which we need when adding posts back in.

We can use the following function in order to add the posts menu as a sub menu item.

https://gist.github.com/wpmark/1796f08a353ae8ffa06f

You will notice that the menu slug we have passed above is edit.php which is the slug of the posts top level page. We could have passed a final arg which would be a callback function, but as the posts page already exists we don’t need to.

Correcting Menu Hierarchy

One thing I have come across when working with menu items is that you also need to alter the menu hierarchy. For example if we move posts into another menu it works fine, however when we now click on the posts sub menu item, it closes the top level item we were in because the posts parent file is not set, as originally it was a top level menu item. We can correct this using the parent_file filter.

https://gist.github.com/wpmark/d9d1a461cdeb5073585c

This will now keep the top level page open when on the sub page of posts. There are one or two strange goings on with this filter that sometimes prevent this from working. I found in particular moving pages to a sub level menu this caused problems on. This trac ticket offered a fix.