1. Home
  2. Docs
  3. Application Framework
  4. Annotations Reference
  5. Settings

Settings

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');
Was this article helpful to you? Yes No

How can we help?