e107 Plugin Admin Menus

Between the e107 Wiki and the YourFirstPlugin starter plugin, there is enough information out there to get started making your own plugins.

I thought that I would focus on individual topics, rather than starting from the beginning.

That being said, on to e107 Plugin Admin Menus.

The Two Pieces Of An Admin Menu

Piece One:
In order to display a custom menu on the side of your plugin admin pages, you need to create a PHP file named "admin_menu.php". Every time you go to your plugin admin pages, e107 checks to see if the "admin_menu.php" file exists. If it does exist, e107 displays the contents of "admin_menu.php", if not, e107 will display it's own menu.

Piece Two:
The standard way that e107 admin menus work is, when you switch between plugin admin pages, the menu will somehow track where you are with some type of visual cue. If you use the standard admin theme (Jayya), the arrows to the left of the menu link will be red if you are on that page.

In order to do this, you will need to include a Unique ID for each one of your admin pages so the menu can keep track of where the user is.

The Setup

Here is the list of files in my plugin:
plugin.php // The Installation File
admin_menu.php // The Admin Menu
admin_config.php // First Menu Link
admin_display_settings.php // Second Menu Link
admin_other_settings.php // Third Menu Link
admin_readme.php // Fourth Menu Link

Adding Unique ID's

First, lets add Unique ID's to to admin pages:

admin_config.php
$pageid = "admin_menu_01";

admin_display_settings.php
$pageid = "admin_menu_02";

admin_other_settings.php
$pageid = "admin_menu_03";

admin_readme.php
$pageid = "admin_menu_04";

A menu item is a multi-dimensional array which has three parts; ID, Text and Link

A Basic Menu

global $pageid;

$menutitle = "My Plugin Menu";

$links["admin_menu_01"]['text'] = "Main Settings";
$links["admin_menu_01"]['link'] = "admin_config.php";

$links["admin_menu_02"]['text'] = "Display Settings";
$links["admin_menu_02"]['link'] = "admin_display_settings.php";

$links["admin_menu_03"]['text'] = "Other Settings";
$links["admin_menu_03"]['link'] = "admin_other_settings.php";

$links["admin_menu_04"]['text'] = "Readme.txt";
$links["admin_menu_04"]['link'] = "admin_readme.php";

show_admin_menu($menutitle, $pageid, $links);

First we make sure that the Unique ID is available to the menu by accessing the global "$pageid" variable.

Then we give the menu a title with the $menutitle variable.

Next we build the links.

The first array key is the Unique ID. For each Unique ID, we add the link Text and the name of the page we are linking to.

Finally, we call the "show_admin_menu()" function to parse what we send to it and display the menu. The first three arguments to the "show_admin_menu()" function are the "Menu Title", the global variable that holds the "Unique Page ID" and the multi-dimensional array that contains the menu link information, in that order.

As long as you stick to this formula, the menu will know what page the user is on and relay that to the user with the visual queue I talked about above.

A Better Menu

This menu will automate a lot of the above code:

global $pageid;

$menutitle = "My Plugin Menu";

$butname[] = "Main Settings";
$butlink[] = "admin_config.php";
$butid[] = "admin_menu_01";

$butname[] = "Display Settings";
$butlink[] = "admin_display_settings.php";
$butid[] = "admin_menu_02";

$butname[] = "Other Settings";
$butlink[] = "admin_other_settings.php";
$butid[] = "admin_menu_03";

$butname[] = "Readme.txt";
$butlink[] = "admin_readme.php";
$butid[] = "admin_menu_04";

for ($i=0; $i < count($butname); $i++) {
$links[$butid[$i]]['text'] = $butname[$i];
$links[$butid[$i]]['link'] = $butlink[$i];
}

show_admin_menu($menutitle, $pageid, $links);

Conclusion

You can now create a Plugin Admin Menu that is integrated into your site and theme of choice, while giving your users a visual clue as to which page they are on.

I will be revisiting this topic at a later date to talk about the "show_admin_menu()" function in more depth, and to show you how to create menu items with sub-links.