Hotaru Docs


Creating a Plugin Settings Page

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)
    if (!$h->isSetting('myplugin_checkbox'))
         // setting name, setting value, plugin name (if not this one)    
         $h->updateSetting('myplugin_checkbox', 'checked'); 

3. Make a settings file

Make a new file in your plugin folder called plugin_name_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 Plugin 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') { 
    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
    // 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
    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   
    // 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.

Getting StartedDesign and LayoutPlugin DevelopmentAdvanced TopicsFunction ReferenceTroubleshooting