You are here: start » plugin_tutorial_admin

Plugin Tutorial: Administration

As the front-end basically works, it's time to develop the back-end (i.e. the admin mode). So create an empty file admin.php in the plugin's folder. If you log in as admin, you can see the new entry “Visitors_online” in the plugin menu. To make this new menu item useful, you have to add some lines to admin.php:

if (isset($visitors_online) && $visitors_online == 'true') {
    $o .= print_plugin_admin('off');
    switch ($admin) {
    case '':
        $o .= 'This is the intro page of the plugin';
        $o .= plugin_admin_common($action, $admin, $plugin);

The if guard is mandatory to avoid that the code is executed, if any action unrelated to your plugin is called. The global $visitors_online is set to 'true' by CMSimple_XH, if the plugin is called for in the back-end.

CMSimple_XH 1.6.3 is supposed to introduce the function XH_wantsPluginAdministration() to be used for this guard. It is recommended to use this function instead for future compatibility:
if (function_exists('XH_wantsPluginAdministration') 
    && XH_wantsPluginAdministration('visitors_online') 
    || isset($visitors_online) && $visitors_online == 'true'
) {

If it's your plugin's turn, typically the first thing is to display the plugin menu. The simplest solution is to append the result of print_plugin_admin() to $o. This writes the default plugin menu to the (X)HTML output (actually to the content area).

Then you have to dispatch on the actual action that is requested. By convention CMSimple_XH uses two GET/POST parameters to specify the action: “admin” and “action”. These parameters are available in the global $admin resp. $action. If you look at the URL when a plugin is selected in the plugin menu, you see that there's no admin parameter, so $admin == “”. This signals that the intro page of the plugin is requested, and so we act accordingly. For a real plugin you'll want to display more useful information, such as the version of the plugin, where it can be found on the web, some usage information etc.

If $admin != “” we forward the handling to plugin_admin_common() which caters for the default actions, such as handling the configuration and language settings, which already are fully functional. Please note that the actual arguments for the call to plugin_admin_common() don't matter, as the function effectively ignores them. This behavior has never been changed, as some plugins might rely on it.

If you like to offer additional non-standard features in the back-end, you should change the argument to print_plugin_admin() from 'off' to 'on'. This will display the menu item “Main Settings”. You have to handle all actions related to this menu item yourself. So add a new case clause to the switch:

        break; // this line was already there
    case 'plugin_main':
        $o .= visitors_admin_main();
    default: // this line was already there

Now you have to write the function visitors_admin_main() which should return the desired (X)HTML output. If you have the need for several actions (such as displaying a form and handling its submission) you might use the action parameter. This can have an arbitrary value, and you can dispatch on this in visitors_admin_main().

« Configuration | Escaping of Strings »

You are here: start » plugin_tutorial_admin
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
Valid XHTML 1.0 Valid CSS Driven by DokuWiki