There are three different annotations that work together to create settings pages in the WP Admin.
@MWP\WordPress\Options( menu="My Plugin", title="My Plugin Options", capability="manage_options" )
@MWP\WordPress\Options\Section( title="General Settings", description="Basic config options." )
@MWP\WordPress\Options\Field( name="field_name", title="Field Title", type="text", default="" )
- The ‘Options’ annotation is used to define the settings page parameters. It should be used first.
- The ‘OptionsSection’ annotation is used to start a new section of options on the settings page.
- The ‘OptionsField’ annotation is used to add a setting and the associated input element to change it.
@MWP\WordPress\Options
This annotation must be used first to designate the options page for managing the settings. The class it is used on should extend the MWP\Framework\Plugin\Settings
class, which contains the base methods used to access and save the settings from the page.
Params
menu="My Plugin"
(optional) / {default: %Plugin Name%} – The name of the menu link for the settings page. Defaults to the plugin name if not provided.
title="My Plugin Options"
(optional) / {default: %Plugin Name% + Options} – The title of the settings page. Defaults to the plugin name + ‘ Options’ if not provided.
capability="manage_options"
(optional) / {default: “manage_options”} – The administrative capability required to access the settings page.
@MWP\WordPress\Options\Section
This annotation must be placed after the ‘@MWP\WordPress\Options’ annotation. It begins the grouping of options fields on the settings page. Any options fields that are specified after this annotation will be grouped into the same section.
Params
menu="My Plugin"
(optional) / {default: %Plugin Name%} – The name of the menu link for the settings page. Defaults to the plugin name if not provided.
title="My Plugin Options"
(optional) / {default: %Plugin Name% + Options} – The title of the settings page. Defaults to the plugin name + ‘ Options’ if not provided.
capability="manage_options"
(optional) / {default: “manage_options”} – The administrative capability required to access the settings page.
@MWP\WordPress\Options\Field
This annotation is used to specify individual settings fields which can be managed on the settings page, and which will store values which can be retrieved by the settings class in the plugin.
Params
name="field_name"
(required) – Specifies the name of the option. This is the name that the setting will be accessible by from the settings class.
title="Field Title"
(required) – The title of the form field
type="select"
(required) / – The type of form element to use for the option field
options={}
(optional) / {default: {}} – For fields that utilize options (such as select, radio, checkboxes, etc), this is a static array of the options that are available, or a string which contains a method name in the class which can be called to return an array of values to use for the field options.
@Example Code
use MWP\Framework\Plugin\Settings as BaseSettings;
/**
* Plugin Settings
*
* @MWP\WordPress\Options
* @MWP\WordPress\Options\Section( title="General Settings" )
* @MWP\WordPress\Options\Field( name="plugin_title", type="text", title="Page Title" )
* @MWP\WordPress\Options\Field( name="plugin_page", type="select", title="Select Page", options="pluginPageOptions" )
*/
class Settings extends BaseSettings
{
/**
* Instance Cache - Required for singleton
* @var self
*/
protected static $_instance;
/**
* Get Plugin Page Select Options
*
* @param string $currentValue The current settings value
* @return array
*/
public function pluginPageOptions( $currentValue=NULL )
{
$options = array();
/* Create list of wordpress pages */
foreach( get_pages() as $page )
{
$post_title = htmlentities( $page->post_title );
$post_name = htmlentities( $page->post_name );
$options[ $page->ID ] = "{$post_name} ({$post_title})";
}
return $options;
}
}
Using Settings
To use settings, you must instantiate your settings class and then attach it to WordPress. To retrieve your settings using your plugin instance, the settings must also be added to your plugin.
use Vendor\Namespace\Plugin as MyPlugin;
use Vendor\Namespace\Plugin\Settings;
use MWP\Framework\Framework;
/* Create new instance of settings */
$settings = new Settings();
/* Add settings page to WordPress */
Framework::instance()->attach( $settings );
/* Make settings available through your plugin */
$myPlugin = MyPlugin::instance();
$myPlugin->addSettings( $settings );
/* Retrieve the existing settings via your plugin */
$plugin_title = $myPlugin->getSetting('plugin_title');
$plugin_page = $myPlugin->getSetting('plugin_page');