Building the Plugin’s Settings Page

The first thing that I wanted to get done with the plugin was to setup and show a Settings page where users can configure the plugin. I figured, I’d start small and only have one option for now (the URL to the Gallery2 installation) so I can get the knowledge of building the page and get the framework for all the other settings setup.

Getting the whole thing done was not that difficult but it did take some digging around due to the very bad descriptions in the WP Codex pages. A very helpful source of information was this page.

Building a WP plugin settings page consists of three major steps:

1. Building the separate settings sections – this is done through a few API calls and callbacks
2. Registering/adding the new page to the “Settings” section of the Admin panel.
3. Rendering the page itself – this is done through a action that we register during step 2.

For this example/tutorial, I am going to use example code directly out of the plugin that I am working on because it is going to be much easier.

The first thing that needs to be done is to build the separate sections on our own Settings page. You might have seen this on different plugins – their settings are divided into sections on the page, each with its own heading and description. For now, I only have one section but the building block are there for the future.

First, we need to register the action which will call the callback that registers all our settings and sections. This is done through the add_action function:

add_action("admin_menu", array(&$this, "admin_menu"));
add_action("admin_init", array(&$this, "init_admin"));

What this does is hook a callback onto each of the admin_menu and admin_init hooks. The admin_menu hook will call our admin_menu method, which will add our Settings page to the Admin panel. The admin_init hook, on the other hand, will call our init_admin method, which will register all our sections and settings.

The first callback that gets run is, of course, the init_admin method. As I said above, this method will register all our settings and setup all our sections. We’ll look at that in a bit but first, there are a few class variables that we are going to need for the rest to make sense:

  /* Settings tags */
  private $WP_G2_OPTION_NAME = "wp-g2-options";
  private $WP_G2_OPTION_GROUP = "wp-gallery2-option-group";
  private $WP_G2_OPTION_SECT_GENERAL = "wp-gallery2-options";
  private $WP_G2_OPTION_PAGE_NAME = "wp-gallery2-settings";

The above variables will be used in the code sections below as various tags and labels. I found it much easier to use class variables through-out the code instead of the strings because it made it easier to understand the relationships between the values in the different calls.

OK, let proceed to the actual code:

  public function init_admin() {
    register_setting($this->WP_G2_OPTION_GROUP, $this->WP_G2_OPTION_NAME,
		     array(&$this, "validate_options"));

    /* Add the General section to the Option Page */
    add_settings_section($this->WP_G2_OPTION_SECT_GENERAL, "General Settings",
			 array (&$this, "settings_section_general"),
			 $this->WP_G2_OPTION_PAGE_NAME);
    foreach (array_keys ($this->options) as $option) {
      add_settings_field($option, "Gallery2 URL", array(&$this, "settings_field"),
			 $this->WP_G2_OPTION_PAGE_NAME,
			 $this->WP_G2_OPTION_SECT_GENERAL, $option);
    }
  }

The method above registers all our settings with WP (for now we only have one) and also defines all our sections along with their fields/options. Let’s look at the method line-by-line:

register_setting($this->WP_G2_OPTION_GROUP, $this->WP_G2_OPTION_NAME,
		     array(&$this, "validate_options"));

register_setting is used to register the individual settings with WP. The preferred method for using setting with WP is to register one “setting” which is actually an array of all the options the plugin needs. This way, plugins done’ end up cluttering the database. The WP core takes care of serializing and de-serializing the array.

• The first argument to the register_setting function is a tag that will be used to group all the options.
• The second argument is the name of the option. Since I am using an array, this is the name of the array.
• The third argument is a function which will be used to validate the options that the user has supplied. Currently, I am using this function to check whether the user want to reset the option(s) to their default values. More on that later…

The next line in the method is:

add_settings_section($this->WP_G2_OPTION_SECT_GENERAL, "General Settings",
			 array (&$this, "settings_section_general"),
			 $this->WP_G2_OPTION_PAGE_NAME);

add_settings_section is used to add a section to an new or existing page. Just as the name implies, a section is a collection of logically related option visually represented together. With this call we add a new section to our own setting page (as opposed to adding a new section to one of the already existing WP pages – General, Writing, Reading, etc.)

• The first argument to the function is, again, a unique tag by which this section is to be identified. This tag will be used later to tell WP which sections to display where.
• The second argument is the title of the section. The title will be displayed with bold text as a heading.
• The third argument is a callback which is used to display any section descriptions, help text, etc. We’ll look at the settings_section_general method later.
• The fourth argument is the page name on which we want this section to be displayed. If we were to use “general”, instead of our name, the section would be displayed in the Settings->General page.

The final line in our method is the one that adds the actual option:

add_settings_field($option, "Gallery2 URL", array(&$this, "settings_field"),
			 $this->WP_G2_OPTION_PAGE_NAME,
			 $this->WP_G2_OPTION_SECT_GENERAL, $option);

add_settings_field adds an option to an already existing section on a page where:

• The first argument is the option name.
• The second argument is the title to display next to the option.
• The third argument is a callback used to generate the HTML code which displays the option.
• The fourth argument is the page on which we want the option to appear
• The fifth argument is the section in which we want the option to appear
• The sixth argument is an argument to be passed to the callback.

Now we have registered all our options and sections. The next step happens when the user goes into the Admin panel and WP calls the callback hooked to the admin_menu hook:

  public function admin_menu () {
    wp_enqueue_script ("wp-g2-ajax", WP_PLUGIN_URL . "/wp-gallery2/js/ajax.js",
		       array("jquery"));

    if (function_exists('add_options_page'))
      add_options_page("WP-Gallery2 Options Page", "WP-Gallery2", 8,
		       $this->WP_G2_OPTION_PAGE_NAME, array(&$this, "admin_page"));
  }

Two things happen here – the first is that we enqueue a small AJAX Java script which will hooks our option to a validation function (this is a different validation function – it checks whether the URL given points to a Gallery2 installation).
The second part is the important one here – it checks whether the add_options_page function exists and if it does, it calls it to register our settings page.

The arguments here are:

• The top level title header of the page
• The link title which will be displayed in the Settings side submenu
• The capability level required to access this page
• The page name tag.
• The callback which will output the HTML of the page

Now, you can see where the page name tag comes into play. Above, we registered our option sections and option fields to belong to a certain page name. Here, we tell WP how to tie all of those in when displaying the Settings pages.

There are a couple of other things that need to get setup before our settings page is complete. There are a few callbacks that need to be written.

The first one is the callback that displays the help text and section description. We used it in the add_settings_section call. Here is the function:

  public function settings_section_general() {
      echo "<p>General plugin settings</p>";
  }

This callback can output any valid HTML code that is needed.

The second callback is the one that outputs the HTML code for the option fields (that’s the one we used in the add_settings_field call):

public function settings_field($option) {
    echo '<input id="'.$option.'" name="'.$this->WP_G2_OPTION_NAME.
      '['.$option.']" type=text value="'.$this->options[$option].'" />'.
      '<span class="description" id="validated"></span><br />';
    echo '<span class="description">'.$this->option_fields[$option].
      '</span>';
  }

Because there is nothing special about our only option, we can use a generic input field for the option. One thing that needs to be mentioned is that id attribute of the input tag needs to be the name of the option.

The final callback that we need is the one that displays the actual page (the one used in the add_options_page). Here is the code I have:

public function admin_page () {

    echo '<div class="wrap">
<h2>WP-Gallery2 Options</h2>
<form method="post" action="options.php">';
    settings_fields($this->WP_G2_OPTION_GROUP);
    do_settings_sections($this->WP_G2_OPTION_PAGE_NAME);
    echo '<p class="submit">
<input type="submit" class="button-primary" value="'. _('Save Settings') .'" />
<input type="submit" name="wp-gallery2-reset" value="'._('Reset Options').'" />
</p>
</form>
</div>';
  }

The settings_fields call outputs some code that sets up some fields needed to correctly process the HTML form. As you can see, the argument to the function is the option group that we defined when we registered the settings.

The next important call is the one to do_settings_sections. This call is the one that actually outputs all the settings to the page. The argument to the function is the page tag that we have defined.

Finally, there are the two submit buttons – one to submit the form and update the settings and another to submit the form and reset the settings.

Resetting the settings is a topic for another post…

Related Posts

• Resetting plugin settings
  04 March 2010 3:11 PM | No Comments

  As promised in a previous post, I wanted to write about resetting WordPress plugin settings. The mechanism for updating the settings that I outlined in that post does allow for [...]

  Read More
• Passing and receiving query variables
  26 February 2010 8:05 PM | No Comments

  One thing that I knew I wanted to be able to do with this plugin is to mimic the behavior of any Gallery2 site – namely, the ability to show [...]

  Read More
• Tagged Posts Widget
  06 October 2010 5:57 PM | 11 Comments

  With the upgrade of my site to Arras 1.5.0.1, I started work on my own child theme (you can see the results on the main page). One of the things [...]

  Read More
• WP-Gallery2 plugin loading galleries through AJAX
  12 March 2010 2:54 PM | No Comments

  As of version 0.7, the WP-Gallery2 plugin can use AJAX calls to load the content of galleries. What this means is that the page can load faster and the user [...]

  Read More
• How to Add Additional Tabs to the Arras’ Tabbed Sidebar Widget
  01 March 2011 1:53 PM | 9 Comments

  Recently, I had a visitor to my website ask a very interesting question after reading the post on the Tagged Post Widget – How can I add more tabs to [...]

  Read More