Creating Your First Plugin: Adding Custom Admin Pages and Settings

WordPress’s unparalleled flexibility largely comes from its robust plugin architecture. For developers, this means the power to extend core functionalities, integrate third-party services, or simply provide tailored experiences for site administrators. This comprehensive guide will walk you through the foundational steps of creating a plugin that introduces a new top-level menu item to your WordPress admin dashboard, complete with a dedicated settings page and custom options.

By the end of this tutorial, you’ll have a working plugin and a clear understanding of how to build more complex and user-friendly admin interfaces.

1. Setting Up Your Plugin File

Every WordPress plugin starts with a single PHP file containing a header comment. This header provides WordPress with essential information about your plugin.

First, create a new folder named my-custom-settings-plugin inside your wp-content/plugins/ directory. Inside this folder, create a file named my-custom-settings-plugin.php.

Add the following header to my-custom-settings-plugin.php:

<?php
/**
 * Plugin Name: My Custom Settings Plugin
 * Plugin URI:  https://yourwebsite.com/my-custom-settings-plugin
 * Description: A basic plugin demonstrating custom admin pages and settings.
 * Version:     1.0.0
 * Author:      Your Name
 * Author URI:  https://yourwebsite.com
 * License:     GPL-2.0+
 * License URI: http://www.gnu.org/licenses/gpl-2.0.txt
 * Text Domain: my-custom-settings-plugin
 */

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

2. Adding a Custom Admin Menu Page

The add_menu_page() function is central to introducing new top-level menu items to the WordPress admin. We’ll hook this function into the admin_menu action.

<?php
// ... (previous plugin header and exit statement)

function mcs_add_admin_menu() {
    add_menu_page(
        'My Custom Settings',          // Page title
        'Custom Settings',             // Menu title
        'manage_options',              // Capability required to access the page
        'my-custom-settings',          // Menu slug (unique identifier for your page)
        'mcs_settings_page_callback',  // Callback function to render the page content
        'dashicons-admin-generic',     // Icon URL or Dashicon class
        80                             // Position in the menu (optional, higher value = lower position)
    );
}
add_action( 'admin_menu', 'mcs_add_admin_menu' );

/**
 * Renders the content of the custom settings page.
 */
function mcs_settings_page_callback() {
    // Check user capabilities
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }

    // Show success/error messages - catches any messages added by add_settings_error()
    settings_errors();
    ?>
    <div class="wrap">
        <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
        <form action="options.php" method="post">
            <?php
            // Output security fields for the registered setting group
            settings_fields( 'my_custom_settings_group' );

            // Output setting sections and their fields
            // The argument 'my-custom-settings' refers to the page slug
            do_settings_sections( 'my-custom-settings' );

            // Output save button
            submit_button( 'Save Settings' );
            ?>
        </form>
    </div>
    <?php
}

3. Registering Custom Settings

Before you can display input fields and save their values, you need to register your settings, sections, and fields with WordPress’s Settings API. This is typically done using the admin_init hook.

• register_setting(): Registers an individual setting/option.
• add_settings_section(): Adds a logical grouping for related settings fields.
• add_settings_field(): Adds an individual input field within a section.

<?php
// ... (previous code)

/**
 * Registers the custom settings, sections, and fields.
 */
function mcs_register_settings() {
    // 1. Register a setting group
    // This tells WordPress how to handle the 'my_custom_text_field' option
    register_setting(
        'my_custom_settings_group',     // Option group (must match settings_fields() argument in form)
        'my_custom_text_field',         // Option name (the key used to store the value in wp_options)
        'mcs_sanitize_callback'         // Sanitize callback function for this option
    );

    // 2. Add a settings section
    // This creates a visual grouping on your settings page.
    add_settings_section(
        'mcs_main_section',             // ID of the section (unique identifier)
        'General Settings',             // Title of the section displayed to the user
        'mcs_section_callback',         // Callback function to render section description
        'my-custom-settings'            // Page slug this section belongs to
    );

    // 3. Add a settings field to the section
    // This defines the input field itself.
    add_settings_field(
        'mcs_text_field',               // ID of the field (unique identifier within the section)
        'Custom Text Input',            // Title of the field displayed to the user
        'mcs_text_field_callback',      // Callback function to render the actual input field HTML
        'my-custom-settings',           // Page slug this field belongs to
        'mcs_main_section',             // Section ID this field belongs to
        [                               // Arguments to pass to the field callback function
            'label_for' => 'my_custom_text_field',
            'class'     => 'mcs-text-field-class',
        ]
    );
}
add_action( 'admin_init', 'mcs_register_settings' );

4. Defining Callbacks for Sections, Fields, and Sanitization

For each registered section and field, you need a callback function to render its content. You also need a sanitization callback to clean and validate user input before it’s saved to the database.

<?php
// ... (previous code)

/**
 * Renders the description for the 'General Settings' section.
 */
function mcs_section_callback() {
    echo '<p>Configure the general settings for your plugin here.</p>';
}

/**
 * Renders the HTML for the 'Custom Text Input' field.
 * @param array $args Arguments passed from add_settings_field().
 */
function mcs_text_field_callback( $args ) {
    // Retrieve the current saved option value.
    $option = get_option( 'my_custom_text_field', '' ); // Default to empty string if not set
    ?>
    <input type="text"
           id="<?php echo esc_attr( $args['label_for'] ); ?>"
           name="<?php echo esc_attr( $args['label_for'] ); ?>"
           value="<?php echo esc_attr( $option ); ?>"
           class="regular-text"
           placeholder="Enter some text here">
    <p class="description">This is a custom text field for your plugin.</p>
    <?php
}

/**
 * Sanitizes and validates the input for 'my_custom_text_field'.
 * @param string $input The raw input value from the form.
 * @return string The sanitized input value.
 */
function mcs_sanitize_callback( $input ) {
    $new_input = sanitize_text_field( $input ); // Basic sanitization for text

    // Example: Add custom validation
    if ( ! empty( $new_input ) && strlen( $new_input ) < 5 ) {
        add_settings_error(
            'my_custom_text_field',             // Setting ID (should match option name)
            'my_custom_text_error',             // Unique error code
            'Input must be at least 5 characters long.', // Error message
            'error'                             // Message type (error/updated)
        );
        return get_option( 'my_custom_text_field' ); // Return old value on validation error
    }

    return $new_input;
}

Conclusion

Congratulations! You’ve just created your first functional WordPress plugin that adds a custom admin menu item, a dedicated settings page, and registers a custom setting field. This foundational knowledge is crucial for building powerful and user-friendly WordPress plugins.

From here, you can expand by adding more settings fields (checkboxes, radio buttons, select dropdowns), multiple sections, tabs for organizing complex options, or even integrate with other WordPress APIs. Experiment, explore the WordPress Developer Resources, and happy coding!