WordPress Settings API: Multiple Forms On Same Page

This tutorial will show you how to add multiple forms on the same page using the Settings API.

NOTE: if what you need is multiple sections in a single form, then read my other article Multiple sections on the same settings page

Before you continue, read the first part of the article Multiple sections on the same settings page where we made a simple settings page with a single section in a single form.

The result page looks like this:

Settings API single section
Settings page with single section

Adding Multiple Forms

Function Reference

Let’s first have a look to some of the main functions defined by the Settings API, and in particular to some of their parameters:

add options page

Add sub menu page to the Settings menu.

(string) (required) The slug name to refer to this menu by (should be unique for this menu).
Default: None

Note: this will be the slug in our URL (see print screen above).

add settings section

Settings Sections are the groups of settings you see on WordPress settings pages with a shared heading. In your plugin you can add new sections to existing settings pages rather than creating a whole new page. This makes your plugin simpler to maintain and creates less new pages for users to learn. You just tell them to change your setting on the relevant existing page.

(string) (required) The menu page on which to display this section. Should match $menu_slug from Function Reference/add theme page
Default: None

Note: in our case it should match the $menu_slug from Function Reference/add options page.

do settings sections

Prints out all settings sections added to a particular settings page.

(string) (required) The slug name of the page whose settings sections you want to output. This should match the page name used in add_settings_section().
Default: None

Note: it should thus match the $menu_slug from Function Reference/add options page.

settings fields

Output nonce, action, and option_page fields for a settings page. Please note that this function must be called inside of the form tag for the options page.

(string) (required) A settings group name. This should match the group name used in register_setting().
Default: None

register setting

Register a setting and its sanitization callback.
This is part of the Settings API, which lets you automatically generate wp-admin settings pages by registering your settings and using a few callbacks to control the output.
This function can also be used to register settings that will be shown on the default WP settings pages like media or general. Once the setting is registered you can add it to an existing section with add_settings_field() or create a new section with add_settings_section() and add it to that.

(string) (required) A settings group name. Must exist prior to the register_setting call. This must match the group name in settings_fields()
Default: None

« Hack »

Having all these functions in mind, let’s try to figure out how we can add multiple forms on the same page. In addition to our first section called “Main Settings”, let’s add a second section in a separate form called “Additional Settings”.

We will modify and create a new form in our settings page by updating the function create_plugin_settings_page() (specified in the $function parameter of add_options_page()). It is in that function that we created our first form, and by attempting to add a second form, we quickly realize that the Settings API is limiting us to a single form:
do_settings_sections() will print all the sections we defined (as it requires as argument the slug of our options page). Though, what we would like to do is to separate our two sections into two forms, and thus we inherently want two do_settings_sections() calls.

To achieve this, we won’t pass the page slug as specified in the API to the do_settings_sections() function, but instead we can pass for example the page slug followed by the section name to make the string unique per section. Thus instead of do_settings_sections( 'test-plugin' );, we will have do_settings_sections( 'test-plugin-main-settings-section' ); in our first form and do_settings_sections( 'test-plugin-additional-settings-section' ); in our second form.

We must change the $page parameter of add_settings_section() consequently. Note also that we will have to register our fields from our different sections in different option groups.

Below is the modified register_settings() function:

This is how our page with multiple forms should look like:

Settings API multiple forms
Settings page with multiple forms

And here is the full code of the settings page:

Below you will find a RAR file containing three plugins that you can paste to your plugins directory, demonstrating a settings page containing:

  1. a single section
  2. multiple sections
  3. multiple forms

Activate the plugins and have a look under the Settings menu.


One thought on “WordPress Settings API: Multiple Forms On Same Page”

Post a Comment