1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

[Docs] Creating a Plugin Settings Page

Discussion in 'Developing Plugins' started by Nick, Aug 2, 2009.

  1. Nick

    Nick Well-Known Member

    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:

    PHP:
     hooksadmin_plugin_settingsadmin_sidebar_plugin_settings
    2. Add default settings

    Add a default setting in the install_plugin function:

    PHP:
    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)

    PHP:
    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.

    PHP:
    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.

    PHP:
    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.
     
    Last edited: Jan 6, 2010

Share This Page