Settings API in Wordpress - Step-by-Step Execution

Concept Flow - Settings API

Start Plugin Initialization

↓

Register Setting

↓

Add Settings Section

↓

Add Settings Fields

↓

Render Settings Page

↓

User Submits Form

↓

Validate & Save Data

↓

Display Updated Settings

↓

End

This flow shows how WordPress Settings API registers settings, adds sections and fields, renders the page, and saves user input.

Execution Sample

Wordpress

<?php
add_action('admin_init', function() {
  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() {
    $val = get_option('my_option_name');
    echo "<input type='text' name='my_option_name' value='" . esc_attr($val) . "' />";
  }, 'my_page', 'my_section');
});

Registers a setting, adds a section and a field with an input box on a settings page.

Execution Table

Step	Action	Function Called	Effect	State Change
1	Plugin loads and hooks admin_init	add_action('admin_init', callback)	Callback registered for admin_init	Callback ready
2	admin_init fires	register_setting('my_option_group', 'my_option_name')	Setting registered	Setting 'my_option_name' registered
3	Add settings section	add_settings_section('my_section', 'My Section', null, 'my_page')	Section added to 'my_page'	Section 'my_section' added
4	Add settings field	add_settings_field('my_field', 'My Field', callback, 'my_page', 'my_section')	Field added to section	Field 'my_field' added
5	Render settings page	do_settings_sections('my_page')	Section and field output HTML	Settings page ready
6	User submits form	submit POST data	Data sent to server	Form data received
7	Validate and save	register_setting validation callback (if any)	Data validated and saved	Option 'my_option_name' updated
8	Display updated settings	get_option('my_option_name')	Input field shows saved value	Settings page updated
9	End	-	No further action	Stable state

💡 Process ends after settings page updates with saved data.

Variable Tracker

Variable	Start	After Step 2	After Step 4	After Step 7	Final
my_option_name	undefined	registered (empty)	registered (empty)	saved user value	saved user value
my_section	undefined	undefined	added	added	added
my_field	undefined	undefined	added	added	added

Key Moments - 3 Insights

Why do we need to register a setting before adding fields?

Registering the setting (see Step 2) tells WordPress to accept and save the option. Without it, the field input won't be saved.

What happens if the validation callback rejects the input?

If validation fails during Step 7, the data is not saved and the old value remains. The user sees an error message.

Why do we add sections and fields separately?

Sections group fields logically on the page (Step 3), and fields belong inside sections (Step 4). This organizes the settings UI.

Visual Quiz - 3 Questions

Look at the execution table, what is the state of 'my_option_name' after Step 4?

A Undefined

B Registered but empty

C Saved user value

D Deleted

💡 Hint

Check the variable_tracker column 'After Step 4' for 'my_option_name'

At which step does the user input get saved?

A Step 7

B Step 5

C Step 3

D Step 2

💡 Hint

Look for 'Validate and save' action in the execution_table

If we skip add_settings_section, what changes in the execution?

A Settings page will not render at all

B Fields will be saved but not shown

C Settings page will have no sections but fields may still appear

D Validation will fail

💡 Hint

Refer to Step 3 and Step 4 in execution_table about sections and fields

Concept Snapshot

Settings API quick steps:
1. register_setting to declare option
2. add_settings_section to group fields
3. add_settings_field to add inputs
4. Render page with do_settings_sections
5. User submits form
6. WordPress validates and saves
Use callbacks for rendering and validation.

Full Transcript

The WordPress Settings API helps developers create settings pages easily. First, you register a setting to tell WordPress to accept and save it. Then, you add sections to organize fields on the page. Next, you add fields inside those sections with callbacks that output input elements. When the settings page renders, WordPress shows these inputs grouped by sections. When a user submits the form, WordPress validates the input and saves it to the database. The saved values then appear in the input fields on reload. This flow ensures settings are managed securely and cleanly.

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