Creating a Plugin Settings Page

[Nick]

There are various ways to add a settings page to your plugin, but the method described here is preferable because it separates your settings code from your main code.

1. Add two hooks

Add the admin_plugin_settings and admin_sidebar_plugin_settings hooks at the top of your plugin:

 * hooks: admin_plugin_settings, admin_sidebar_plugin_settings 

2. Add default settings

Add a default setting in the install_plugin function:

public function install_plugin($h)
{
     $h->updateSetting('myplugin_checkbox', 'checked'); // setting name, setting value, plugin name (if not this one)    
 } 

3. Make a settings file

Make a new file in your plugin folder called pluginname_settings.php

4. Make a class

Make a settings class in that file called PluginNameSettings (capitalize each word and no spaces)

class PluginNameSettings
{

} 

5. settings function

This function goes in the above class and will contain the form your users will submit in the Plugn Settings page. Here's a basic example to get you started, but it assumes you've made a language file to store labels and instructions. The resulting form will have one setting, a simple checkbox.

public function settings($h)
{
    // If the form has been submitted, go and save the data...
    if ($h->cage->post->getAlpha('submitted') == 'true') { 
        $this->saveSettings($h); 
    }    
    
    echo "<h1>" . $h->lang["myplugin_settings_header"] . "</h1>\n";
    
    // Get settings from the database if they exist...
    $mycheckbox = $h->getSetting('myplugin_checkbox');

    //...otherwise set to blank:
    if (!$mycheckbox) { $mycheckbox = ''; }

    // A plugin hook so other plugin developers can add settings
    $h->pluginHook('myplugin_settings_get_values');
      
    // The form should be submitted to the admin_index.php page:
    echo "<form name='myplugin_settings_form' action='" . BASEURL . "admin_index.php?page=plugin_settings&amp;plugin=myplugin' method='post'>\n";
    
    echo "<p>" . $h->lang["myplugin_settings_instructions"] . "</p><br />";
    
    // The checkbox
    echo "<input type='checkbox' name='myplugin_checkbox' value='myplugin_checkbox' " . $mycheckbox . " >&nbsp;&nbsp;" . $h->lang["myplugin_settings_checkbox"] . "<br />\n";    

    // A plugin hook so other plugin developers can show settings
    $h->pluginHook('myplugin_settings_form');
            
    echo "<br /><br />\n";    
    echo "<input type='hidden' name='submitted' value='true' />\n";
    echo "<input type='submit' value='" . $h->lang["main_form_save"] . "' />\n";
    echo "<input type='hidden' name='csrf' value='" . $h->csrfToken . "' />\n";
    echo "</form>\n";
} 

6. save_settings function

This function should also go in the PluginNameSettings class.

public function saveSettings($h)
{
    // Check the status of our checkbox
    if ($h->cage->post->keyExists('myplugin_checkbox')) { 
        $mycheckbox = 'checked'; 
    } else { 
        $mycheckbox = ''; 
    }
 
    // A plugin hook so other plugin developers can save settings   
    $h->pluginHook('myplugin_save_settings');
    
    // Update the setting in the database
    $h->updateSetting('myplugin_checkbox', $mycheckbox);
    
    // This is just a checkbox, so we'll assume it was updated successfully:
    $h->showMessage($h->lang["main_settings_saved"], "green");
    
    return true;    
} 

7. Install the plugin

With that done, all that's left is to reinstall the plugin so the default settings are added to the plugin_settings table. Now you should be able to check and uncheck the setting and have it save accordingly.