How to Create a Form with a Textbox in a WordPress Plugin
As a WordPress plugin developer, you may often need to create an options page that allows users to customize the behavior of your plugin. One common requirement is to include a textbox field where users can input their preferences or settings.
In this blog post, we'll walk through the process of creating a form with a textbox within a WordPress plugin, using the Settings API. This is a well-established and recommended approach for handling plugin options in WordPress.
Understanding the WordPress Settings API
The WordPress Settings API is a powerful tool that allows you to easily create and manage options pages for your plugin. It provides a standardized way to register, sanitize, and display your plugin's settings.
The key components of the Settings API are:
- add_options_page(): This function adds a new options page to the WordPress admin menu.
- register_setting(): This function registers a setting that can be saved and retrieved using the
get_option()
and update_option()
functions.
- add_settings_section(): This function adds a new section to the options page, which can contain one or more settings fields.
- add_settings_field(): This function adds a new settings field to a specific section on the options page.
By using these functions, you can create a clean and organized options page for your plugin, with various input fields and sections.
Step 1: Create the Admin Menu and Settings Page
Let's start by setting up the admin menu and creating the settings page for our plugin. We'll use the add_action()
function to hook into the admin_menu
action and add a new top-level menu item.
// Create custom plugin settings menu
add_action('admin_menu', 'my_cool_plugin_create_menu');
function my_cool_plugin_create_menu() {
// Create a new top-level menu
add_menu_page(
'My Cool Plugin Settings',
'Cool Settings',
'administrator',
__FILE__,
'my_cool_plugin_settings_page',
plugins_url('/images/icon.png', __FILE__)
);
// Call the register settings function
add_action('admin_init', 'register_my_cool_plugin_settings');
}
In this code, we're creating a new top-level menu item in the WordPress admin with the title "Cool Settings". The my_cool_plugin_settings_page()
function will be called when the user clicks on this menu item, and it's where we'll define the content of the options page.
Step 2: Register the Settings
Next, we'll register the settings that we want to save and retrieve using the register_setting()
function. This tells WordPress to create the necessary database entries for our settings.
function register_my_cool_plugin_settings() {
// Register our settings
register_setting('my-cool-plugin-settings-group', 'new_option_name');
register_setting('my-cool-plugin-settings-group', 'some_other_option');
register_setting('my-cool-plugin-settings-group', 'option_etc');
}
In this example, we're registering three settings: new_option_name
, some_other_option
, and option_etc
. The first parameter of register_setting()
is the name of the settings group, which we'll use later when adding settings fields to the page.
Step 3: Create the Settings Page
Now, let's define the my_cool_plugin_settings_page()
function, which will generate the content of the options page:
function my_cool_plugin_settings_page() {
?>
<div class="wrap">
<h1>Your Plugin Name</h1>
<form method="post" action="options.php">
<?php settings_fields('my-cool-plugin-settings-group'); ?>
<?php do_settings_sections('my-cool-plugin-settings-group'); ?>
<table class="form-table">
<tr valign="top">
<th scope="row">New Option Name</th>
<td><input type="text" name="new_option_name" value="<?php echo esc_attr(get_option('new_option_name')); ?>" /></td>
</tr>
<tr valign="top">
<th scope="row">Some Other Option</th>
<td><input type="text" name="some_other_option" value="<?php echo esc_attr(get_option('some_other_option')); ?>" /></td>
</tr>
<tr valign="top">
<th scope="row">Options, Etc.</th>
<td><input type="text" name="option_etc" value="<?php echo esc_attr(get_option('option_etc')); ?>" /></td>
</tr>
</table>
<?php submit_button(); ?>
</form>
</div>
<?php }
In this code, we're creating a basic options page with a form that includes three text input fields. The settings_fields()
function generates the necessary hidden fields for the Settings API, and the do_settings_sections()
function ensures that any registered sections and fields are displayed.
The get_option()
function is used to retrieve the current values of the registered settings, which are then displayed in the input fields.
Step 4: Adding Validation and Sanitization
To ensure the security and integrity of your plugin's settings, it's important to validate and sanitize the user input. You can do this by adding a sanitize_callback
function to the register_setting()
call.
function register_my_cool_plugin_settings() {
// Register our settings with sanitization callbacks
register_setting('my-cool-plugin-settings-group', 'new_option_name', 'sanitize_text_field');
register_setting('my-cool-plugin-settings-group', 'some_other_option', 'sanitize_text_field');
register_setting('my-cool-plugin-settings-group', 'option_etc', 'sanitize_text_field');
}
In this example, we're using the built-in sanitize_text_field()
function to sanitize the user input. You can also create your own custom sanitization functions if needed.
Get a Free AI Website Audit
Automatically identify UX and content issues affecting your conversion rates with Flowpoint's comprehensive AI-driven website audit.
Step 5: Retrieving and Updating the Settings
Once you've created the options page and registered the settings, you can easily retrieve and update the values using the get_option()
and update_option()
functions.
// Retrieve the value of the 'new_option_name' setting
$new_option_value = get_option('new_option_name');
// Update the value of the 'new_option_name' setting
update_option('new_option_name', 'new_value');
By following these steps, you've created a WordPress plugin with an options page that includes a textbox field. Users can now customize the behavior of your plugin by entering their preferences in the textbox.
Remember, this is just one example of using the WordPress Settings API to create an options page. You can further enhance your plugin's options page by adding more fields, sections, and validation rules as needed.
For more information on the WordPress Settings API and best practices for plugin development, be sure to check out the WordPress Plugin Developer Handbook and the WordPress Codex. And if you're looking for a tool to help you identify and fix technical issues that might be impacting your plugin's conversion rates, you might want to check out Flowpoint.ai