You are currently viewing Creating Your First ‘Hello World’ Plugin with Custom Settings

Creating Your First ‘Hello World’ Plugin with Custom Settings

Spread the love

Diving into WordPress plugin development can seem daunting, but starting with a “Hello World” project is the perfect way to demystify the process. This tutorial will guide you through creating your very first WordPress plugin, complete with a custom settings page to allow users to configure its output. By the end, you’ll have a solid foundation for building more complex and interactive plugins.

Prerequisites

  • A local WordPress development environment (e.g., LocalWP, XAMPP, MAMP).
  • A text editor (e.g., VS Code, Sublime Text).
  • Basic understanding of PHP and HTML.

Step 1: Setup Your Development Environment

First, ensure your local WordPress site is running. Navigate to the wp-content/plugins/ directory within your WordPress installation. This is where all your plugins reside.

Step 2: Create Your Plugin Folder and Main File

Inside the plugins directory, create a new folder named my-hello-world-plugin. Inside this folder, create a PHP file with the same name: my-hello-world-plugin.php.

Open my-hello-world-plugin.php and add the following required header comments. These comments tell WordPress about your plugin.

<?php
/*
Plugin Name: My Hello World Plugin
Plugin URI:  https://yourwebsite.com/my-hello-world-plugin
Description: A simple "Hello World" plugin with custom settings.
Version:     1.0
Author:      Your Name
Author URI:  https://yourwebsite.com
License:     GPL2
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-hello-world-plugin
*/

// Prevent direct file access
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
?>

Save the file. Now, go to your WordPress admin dashboard, navigate to “Plugins” > “Installed Plugins”. You should see “My Hello World Plugin” listed. Click “Activate”.

Step 3: Basic “Hello World” Functionality

Let’s make our plugin do something simple. We’ll display “Hello World!” at the bottom of every page.

Add the following code to your my-hello-world-plugin.php file, below the header comments:

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

/**
 * Display the Hello World text.
 */
function my_hello_world_display_text() {
    echo '<p>Hello World from my first plugin!</p>';
}
add_action( 'wp_footer', 'my_hello_world_display_text' );
?>

The add_action function hooks our my_hello_world_display_text function into the wp_footer action, which executes before the closing </body> tag. Save the file and visit the frontend of your WordPress site. You should see your message!

Step 4: Adding a Custom Settings Page

Now, let’s allow users to change this “Hello World” text. We’ll add a settings page to the WordPress admin menu.

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

/**
 * Add a new top-level menu item to the admin panel.
 */
function my_hello_world_add_admin_menu() {
    add_options_page(
        'My Hello World Settings', // Page title
        'Hello World',             // Menu title
        'manage_options',          // Capability required
        'my-hello-world',          // Menu slug
        'my_hello_world_settings_page_html' // Callback function to render the page
    );
}
add_action( 'admin_menu', 'my_hello_world_add_admin_menu' );

/**
 * Render the settings page content.
 */
function my_hello_world_settings_page_html() {
    // Check user capabilities
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    // Add error/update messages
    settings_errors( 'my_hello_world_messages' );
    ?>
    <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 "myHelloWorldOptionGroup"
            settings_fields( 'myHelloWorldOptionGroup' );
            // Output setting sections and their fields
            // (sections are registered for "myHelloWorldSettingsPage")
            do_settings_sections( 'myHelloWorldSettingsPage' );
            // Output save button
            submit_button( 'Save Settings' );
            ?>
        </form>
    </div>
    <?php
}
?>

Save, then refresh your WordPress admin. You’ll see a new “Hello World” item under “Settings”. Clicking it will show an empty page with a title and a save button, because we haven’t registered any settings yet.

Step 5: Registering Settings and Fields

Now, let’s define the actual setting field where users can input their custom text.

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

/**
 * Register our settings, sections and fields.
 */
function my_hello_world_settings_init() {
    // Register a new setting for "my_hello_world_custom_text"
    register_setting( 'myHelloWorldOptionGroup', 'my_hello_world_custom_text' );

    // Register a new section in the "myHelloWorldSettingsPage" page
    add_settings_section(
        'my_hello_world_section_developers', // ID
        __( 'Custom Text Settings', 'my-hello-world-plugin' ), // Title
        'my_hello_world_section_developers_callback', // Callback to render section intro
        'myHelloWorldSettingsPage' // Page slug this section belongs to
    );

    // Register a new field in the "my_hello_world_section_developers" section, inside the "myHelloWorldSettingsPage" page
    add_settings_field(
        'my_hello_world_field_text', // ID
        __( 'Custom Text', 'my-hello-world-plugin' ), // Title
        'my_hello_world_field_text_callback', // Callback to render field input
        'myHelloWorldSettingsPage', // Page slug this field belongs to
        'my_hello_world_section_developers', // Section ID this field belongs to
        [
            'label_for' => 'my_hello_world_field_text',
            'class'     => 'my-hello-world-row',
            'my_hello_world_custom_data' => 'custom',
        ]
    );
}
add_action( 'admin_init', 'my_hello_world_settings_init' );

/**
 * Render the description for the section.
 */
function my_hello_world_section_developers_callback( $args ) {
    ?><p><?php esc_html_e( 'Configure the text displayed by the plugin.', 'my-hello-world-plugin' ); ?></p><?php
}

/**
 * Render the text field input.
 */
function my_hello_world_field_text_callback( $args ) {
    // Get the value of the setting we've registered with register_setting()
    $option = get_option( 'my_hello_world_custom_text' );
    ?><input
        type="text"
        id="my_hello_world_field_text"
        name="my_hello_world_custom_text"
        value="<?php echo esc_attr( $option ); ?>"
        placeholder="Enter your custom text"
        class="regular-text"
    >
    <?php
}
?>

Refresh the “Hello World” settings page. You’ll now see an input field labeled “Custom Text”.

Step 6: Displaying and Saving the Custom Text

Finally, let’s update our frontend display function to use the text saved in our settings.

Modify your my_hello_world_display_text() function:

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

/**
 * Display the Hello World text.
 */
function my_hello_world_display_text() {
    // Retrieve the custom text from options, with a fallback
    $custom_text = get_option( 'my_hello_world_custom_text', 'Hello World from my first plugin!' );
    // Ensure the output is safe
    echo '<p>' . esc_html( $custom_text ) . '</p>';
}
// ... (rest of the file)
?>

Now, go to “Settings” > “Hello World”, enter some custom text (e.g., “Hello from my awesome plugin!”), and click “Save Settings”. Visit the frontend of your site, and you’ll see your custom text!

Conclusion

Congratulations! You’ve successfully built your first WordPress plugin with a custom settings page. You’ve learned how to:

  • Structure a basic plugin file.
  • Use WordPress action hooks (wp_footer, admin_menu, admin_init).
  • Create an admin options page using add_options_page.
  • Register settings, sections, and fields using the Settings API.
  • Retrieve and display user-configured options.

This “Hello World” plugin serves as a robust starting point. From here, you can expand its functionality, add more settings, incorporate styles and scripts, and much more. Happy coding!

Tags: , , , , , ,

Leave a Reply