DEV Community

Cover image for The Ultimate Guide to Building WordPress Admin Pages with WP Settings Builder
Owais Ahmed
Owais Ahmed

Posted on

The Ultimate Guide to Building WordPress Admin Pages with WP Settings Builder

#webdev #wordpress #tutorial #php

If you’ve ever spent hours wrestling with the WordPress Settings API, you know the pain. It’s powerful, but it can be verbose, confusing, and hard to maintain. Building a simple options page can involve dozens of callbacks, hooks, and boilerplate code. What if you could do it all in a single, readable file with a clean, fluent API?

Enter WP Settings Builder, an open-source framework by WPTechnix that radically simplifies the creation of settings pages for your plugins and themes.

This article will teach you not just how to use it, but why it’s a better approach. We’ll go from a simple "Hello World" example to a feature-rich settings page with tabs, conditional logic, and advanced fields.

The "Why": Solving the Settings API Headache

Before we dive into the code, let’s understand the problem. The native WordPress Settings API forces you to:

  • Scatter your code: Logic is spread across add_menu_page, register_setting, add_settings_section, and add_settings_field calls.
  • Write lots of boilerplate: Each field requires a separate callback function just to render its HTML.
  • Manually handle sanitization: You have to create a sanitization callback for every single setting.
  • Struggle with complex fields: Creating things like date pickers, media uploaders, or AJAX-powered post selectors requires significant custom code and asset enqueuing.

WP Settings Builder solves these problems by providing a unified, object-oriented interface. All your configuration for a page—its title, sections, fields, and tabs—is defined in one place using a chainable, fluent API.

Step 1: Installation and Setup

First things first, let's get the framework into your project. The recommended way is via Composer.

Navigate to your plugin or theme directory and run:

composer require wptechnix/wp-settings-builder
Enter fullscreen mode Exit fullscreen mode

Next, make sure you include the Composer autoloader in your main plugin file or your theme's functions.php.

<?php // plugins/my-awesome-plugin/my-awesome-plugin.php // Require the Composer autoloader. require_once __DIR__ . '/vendor/autoload.php'; // Your plugin code starts here...
Enter fullscreen mode Exit fullscreen mode

That’s it! The framework is now ready to use.

Step 2: The 3-Step Workflow — Your First Settings Page

The framework is built around a simple, memorable 3-step pattern: create, configure, and initialize.

  1. create(): Get a builder instance and create a page.
  2. configure(): Use fluent methods to define the page structure and fields.
  3. init(): Register the page and all its hooks with WordPress.

Let's build a basic settings page under the main "Settings" menu.

<?php use WPTechnix\WP_Settings_Builder\Settings_Builder; add_action( 'admin_init', function() { // 1. CREATE: Get a builder and create a page. // Params: $option_group, $option_name $page = ( new Settings_Builder() )->create( 'my_plugin_settings_group', 'my_plugin_options' ); // 2. CONFIGURE: Set up the page and add fields. $page->set_page_title( 'My Awesome Plugin' ) ->set_menu_title( 'My Plugin' ) ->set_parent_slug( 'options-general.php' ); // Under 'Settings' // Add a section to group our fields $page->add_section( 'general_section', 'General Settings' ); // Add a simple text field $page->add_field( 'license_key', // Field ID 'general_section', // Section ID 'text', // Field Type 'License Key', // Field Label [ 'description' => 'Enter your license key to receive updates.' ] // Field Arguments ); // Add a switch/toggle field $page->add_field( 'enable_awesome_mode', 'general_section', 'switch', 'Enable Awesome Mode', [ 'description' => 'Enable this to make the plugin 110% more awesome.', 'default' => true, ] ); // 3. INITIALIZE: Build the page. $page->init(); });
Enter fullscreen mode Exit fullscreen mode

Add this code to your plugin, and you'll have a fully functional settings page. Notice how readable it is? Everything is in one place, and the fluent, chainable methods (->set_page_title()->...) make the configuration clean and logical.

Step 3: Power-Up with Advanced Fields and Tabs

Simple text fields are great, but modern plugins need more. Let's create a more complex, tabbed settings page for a hypothetical e-commerce plugin.

Organizing with Tabs

When you have many settings, tabs are essential for a good user experience.

// In your configuration chain: $page->add_tab( 'general_tab', 'General', 'dashicons-admin-generic' ); $page->add_tab( 'api_tab', 'API Settings', 'dashicons-admin-network' ); // When adding a section, just specify which tab it belongs to. $page->add_section( 'general_section', 'Store Details', 'general_tab' ); $page->add_section( 'api_section', 'Payment Gateway API', 'api_tab' );
Enter fullscreen mode Exit fullscreen mode

Using Powerful Fields

Now let's add some advanced fields to our new sections. WP Settings Builder comes with over 30 field types, including:

  • color: A WordPress color picker.
  • media: A media library uploader.
  • post: An AJAX-powered search field to select a post, page, or custom post type.
  • wysiwyg: The full WordPress TinyMCE editor. 
// Add a Media Uploader for the store logo $page->add_field( 'store_logo', 'general_section', 'media', 'Store Logo' ); // Add a Post Selector to choose the "Terms of Service" page $page->add_field( 'terms_page', 'general_section', 'post', 'Terms of Service Page', [ 'description' => 'Select the page that contains your terms and conditions.', 'query_args' => [ 'post_type' => 'page' ], // Only search for pages ] ); // Add a secure Password field for the API key $page->add_field( 'api_key', 'api_section', 'password', 'API Secret Key' );
Enter fullscreen mode Exit fullscreen mode

One of the best features is that assets (CSS/JS) for these fields are only loaded if you actually use the field. Use a color picker, and the color picker script is enqueued. If you don't, it isn't. This keeps your admin pages fast and lightweight.

Step 4: Implementing Conditional Logic

Conditional logic is what separates static forms from dynamic experiences. WP Settings Builder has this built-in—no JavaScript required.

Let’s add a field that only appears if a specific option is enabled.

// First, add a switch to enable/disable test mode $page->add_field( 'enable_test_mode', 'api_section', 'switch', 'Enable Test Mode' ); // Next, add a text field that only shows when test mode is ON $page->add_field( 'test_api_key', 'api_section', 'text', 'Test API Key', [ 'description' => 'This key will be used for sandbox transactions.', 'condition' => [ 'field' => 'enable_test_mode', // The ID of the controlling field 'operator' => '==', // The comparison operator 'value' => true, // The value to check against ], ] );
Enter fullscreen mode Exit fullscreen mode

Now, the "Test API Key" field will magically appear and disappear as you toggle the "Enable Test Mode" switch.

Step 5: Retrieving and Using Your Settings

Defining settings is only half the battle. You also need an easy way to retrieve them in your theme or plugin's frontend code.

The framework provides a static helper method to get your page instance and its settings.

use WPTechnix\WP_Settings_Builder\Settings_Builder; function get_my_plugin_option( $key, $default = null ) { // Get the page instance using its unique ID ($option_name) $page = Settings_Builder::get_instance( 'my_plugin_options' ); // If the page exists, get the setting if ( $page ) { return $page->get_setting( $key, $default ); } return $default; } // --- Example Usage --- // Get the store logo ID (returns an attachment ID) $logo_id = get_my_plugin_option( 'store_logo' ); if ( $logo_id ) { echo wp_get_attachment_image( $logo_id, 'medium' ); } // Check if awesome mode is on (returns true/false) if ( get_my_plugin_option( 'enable_awesome_mode' ) ) { // Do something awesome! }
Enter fullscreen mode Exit fullscreen mode

Conclusion: Build Better, Faster

WP Settings Builder isn’t just a tool; it’s a better workflow. It encourages clean, organized, and maintainable code, allowing you to build professional-grade settings pages in a fraction of the time. You can focus on your plugin's features, not on fighting with boilerplate.

You’ve learned how to install the framework, create a basic page, organize it with tabs, add advanced fields, implement conditional logic, and retrieve your settings. You're now equipped to build powerful options pages for your next project.

Ready to dive deeper?

The official documentation is the best place to explore all the available fields and advanced features.

Give it a try on your next project. You’ll never want to go back to the old way again.

Top comments (0)