Settings API in Wordpress - Mini Project: Build & Apply

WordPress Settings API: Create a Simple Plugin Settings Page

📖 Scenario: You want to create a WordPress plugin that lets users save a simple setting, like a welcome message, from the admin dashboard.This setting will be stored and used later by the plugin.

🎯 Goal: Build a WordPress plugin that adds a settings page under the Settings menu. The page will have a text input for a welcome message. Users can save this message using the WordPress Settings API.

📋 What You'll Learn

Create a plugin file with the plugin header

Register a settings section and a settings field using the Settings API

Add a settings page under the Settings menu

Display and save the welcome message setting

💡 Why This Matters

🌍 Real World

Many WordPress plugins need settings pages to let users customize behavior. The Settings API is the standard way to build these pages safely and consistently.

💼 Career

Understanding the WordPress Settings API is essential for WordPress plugin developers and theme developers who want to add configurable options.

1

Create the plugin header and register the settings page

Create a PHP file with the plugin header comment. Then add a function called myplugin_add_admin_menu that uses add_options_page to add a settings page titled "My Plugin Settings" under the Settings menu. Hook this function to admin_menu.

Wordpress

<?php
// Your code here

Hint

Start by writing the plugin header comment. Then create a function named myplugin_add_admin_menu that calls add_options_page with the page title "My Plugin Settings" and menu title "My Plugin". Hook this function to the admin_menu action.

2

Register the setting and add a settings section and field

Create a function called myplugin_settings_init. Inside it, register a setting named myplugin_options using register_setting. Then add a settings section with ID myplugin_section and title "Settings" using add_settings_section. Finally, add a settings field with ID myplugin_welcome_message, label "Welcome Message", and a callback function myplugin_welcome_message_render using add_settings_field. Hook myplugin_settings_init to admin_init.

Wordpress

<?php
/**
 * Plugin Name: My Plugin
 * Description: A simple plugin to demonstrate the Settings API.
 * Version: 1.0
 * Author: Your Name
 */

function myplugin_add_admin_menu() {
    add_options_page(
        'My Plugin Settings',
        'My Plugin',
        'manage_options',
        'myplugin',
        'myplugin_options_page'
    );
}
add_action('admin_menu', 'myplugin_add_admin_menu');

// Register settings, section, and field
function myplugin_settings_init() {
    // Your code here
}
add_action('admin_init', 'myplugin_settings_init');

Hint

Inside myplugin_settings_init, call register_setting with group 'myplugin' and option name 'myplugin_options'. Then add a section with ID 'myplugin_section' and title "Settings". Finally, add a field with ID 'myplugin_welcome_message', label "Welcome Message", and callback myplugin_welcome_message_render. Hook this function to admin_init.

3

Create the callback to render the welcome message input

Create a function called myplugin_welcome_message_render. Inside it, get the saved options using get_option('myplugin_options'). Then output an HTML input of type text with name myplugin_options[welcome_message] and value set to the saved welcome message or empty string if none.

Wordpress

<?php
// Your code here

Hint

Define myplugin_welcome_message_render to get the saved options with get_option('myplugin_options'). Then output an input box with name myplugin_options[welcome_message] and value set safely using esc_attr.

4

Create the settings page form to display and save options

Create a function called myplugin_options_page. Inside it, output a form with method post and action set to options.php. Call settings_fields('myplugin'), do_settings_sections('myplugin'), and add a submit button with text "Save Settings". This form will display the settings fields and save the options.

Wordpress

<?php
// Your code here

Hint

Define myplugin_options_page to output a form with action="options.php" and method="post". Inside the form, call settings_fields('myplugin'), do_settings_sections('myplugin'), and add a submit button with submit_button('Save Settings').

Practice

1. What is the main purpose of the WordPress Settings API?

easy

A. To optimize database queries for faster loading

B. To handle user authentication and login

C. To create and manage settings pages and options safely and easily

D. To create custom post types and taxonomies

Solution

1. Step 1: Understand the role of Settings API

   The Settings API is designed to help developers create settings pages and manage options in a standardized and secure way.

2. Step 2: Compare with other WordPress features

   User authentication, database optimization, and custom post types are handled by other parts of WordPress, not the Settings API.

3. Final Answer:

   To create and manage settings pages and options safely and easily -> Option C

4. Quick Check:

   Settings API = Manage settings pages [OK]

Hint: Settings API is for settings pages, not users or posts [OK]

Common Mistakes:

• Confusing Settings API with user login functions
• Thinking it manages posts or taxonomies
• Assuming it optimizes database queries

2. Which function is used to register a setting group and option name in the WordPress Settings API?

easy

A. register_setting()

B. add_settings_section()

C. add_settings_field()

D. settings_fields()

Solution

1. Step 1: Identify function roles

   register_setting() registers a setting group and option name for saving options.

2. Step 2: Differentiate from other functions

   add_settings_section() adds a section, add_settings_field() adds a field, and settings_fields() outputs nonce fields for the form.

3. Final Answer:

   register_setting() -> Option A

4. Quick Check:

   Register setting = register_setting() [OK]

Hint: register_setting registers options, sections and fields add UI [OK]

Common Mistakes:

• Using add_settings_section to register options
• Confusing settings_fields with registration
• Mixing add_settings_field with option registration

3. What will be the output of the following code snippet in a WordPress settings page?

register_setting('my_option_group', 'my_option_name');
add_settings_section('my_section', 'My Section', null, 'my_page');
add_settings_field('my_field', 'My Field', function() { echo ''; }, 'my_page', 'my_section');

// In the form:
settings_fields('my_option_group');
do_settings_sections('my_page');

What does this code do when the settings page loads?

medium

A. Displays a text input with the saved value of 'my_option_name' inside 'My Section'

B. Shows an error because the callback function is missing

C. Creates a checkbox input instead of a text input

D. Does not display any input because settings_fields is missing

Solution

1. Step 1: Analyze the field callback

   The callback outputs a text input with the name 'my_option_name' and sets its value to the saved option using get_option('my_option_name').

2. Step 2: Check form functions

   settings_fields('my_option_group') outputs necessary nonce and hidden fields, and do_settings_sections('my_page') outputs the registered sections and fields.

3. Final Answer:

   Displays a text input with the saved value of 'my_option_name' inside 'My Section' -> Option A

4. Quick Check:

   Field callback outputs input with saved value [OK]

Hint: Field callback outputs input; settings_fields and do_settings_sections show it [OK]

Common Mistakes:

• Assuming callback is missing or broken
• Thinking input type is checkbox
• Forgetting settings_fields is present

4. Identify the error in this WordPress Settings API code snippet:

register_setting('my_group', 'my_option');
add_settings_section('section_id', 'Section Title', null, 'my_page');
add_settings_field('field_id', 'Field Title', 'my_field_callback', 'my_page', 'section_id');

function my_field_callback() {
  echo '';
}

// In the form:
settings_fields('wrong_group');
do_settings_sections('my_page');

What is the main problem here?

medium

A. The add_settings_section callback is required but set to null

B. The callback function is missing

C. The add_settings_field is missing the page parameter

D. The settings_fields function uses a different group name than register_setting

Solution

1. Step 1: Check group names consistency

   register_setting uses 'my_group' but settings_fields uses 'wrong_group'. They must match for nonce and saving to work.

2. Step 2: Verify other parts

   The callback function exists, page parameter is present, and section callback can be null (optional).

3. Final Answer:

   The settings_fields function uses a different group name than register_setting -> Option D

4. Quick Check:

   Group names must match in register_setting and settings_fields [OK]

Hint: Match group names in register_setting and settings_fields exactly [OK]

Common Mistakes:

• Ignoring mismatch of group names
• Thinking section callback cannot be null
• Assuming missing page parameter

5. You want to create a settings page with two sections: 'General' and 'Advanced'. Each section has multiple fields. Which sequence of Settings API functions correctly sets up this page?

hard

A. add_settings_section('general_section', 'General', null, 'my_page');
add_settings_field('field1', 'Field 1', 'callback1', 'my_page', 'general_section');
register_setting('my_group', 'option1');
add_settings_section('advanced_section', 'Advanced', null, 'my_page');
add_settings_field('field2', 'Field 2', 'callback2', 'my_page', 'advanced_section');

B. register_setting('my_group', 'option1');
register_setting('my_group', 'option2');
add_settings_section('general_section', 'General', null, 'my_page');
add_settings_section('advanced_section', 'Advanced', null, 'my_page');
add_settings_field('field1', 'Field 1', 'callback1', 'my_page', 'general_section');
add_settings_field('field2', 'Field 2', 'callback2', 'my_page', 'advanced_section');

C. register_setting('my_group', 'option1');
add_settings_field('field1', 'Field 1', 'callback1', 'my_page', 'general_section');
add_settings_section('general_section', 'General', null, 'my_page');
add_settings_section('advanced_section', 'Advanced', null, 'my_page');
add_settings_field('field2', 'Field 2', 'callback2', 'my_page', 'advanced_section');

D. register_setting('my_group', 'option1');
register_setting('my_group', 'option2');
add_settings_field('field1', 'Field 1', 'callback1', 'my_page', 'general_section');
add_settings_section('general_section', 'General', null, 'my_page');
add_settings_section('advanced_section', 'Advanced', null, 'my_page');
add_settings_field('field2', 'Field 2', 'callback2', 'my_page', 'advanced_section');

Solution

1. Step 1: Register all settings first

   Use register_setting for each option before adding sections and fields.

2. Step 2: Add sections before fields

   Sections must be added before fields so fields can attach to existing sections.

3. Step 3: Add fields to correct sections

   Use add_settings_field with correct section IDs and page slug.

4. Final Answer:

   Registers settings first, adds sections then fields in the correct order -> Option B

5. Quick Check:

   Register settings -> add sections -> add fields [OK]

Hint: Register settings first, then add sections, then fields [OK]

Common Mistakes:

• Adding fields before sections exist
• Registering settings after adding fields
• Mixing order of sections and fields