Home

This is a quick "getting started" guide that should have you building your theme or plugin in no time. Enjoy!

For this guide, we're going to assume that the slug of your project is your-plugin and the settings library is stored in includes/libraries/origami. Instantiating the settings library would go something like this:

global $your_plugin_options;

if ( ! class_exists( 'Origami' ) ) {
  require_once __DIR__ . 'includes/libraries/origami/class.origami.php';
}

$settings = new Origami( 'your-plugin', 'general', array( 'sysinfo' ), 'network' );
$your_plugin_options = $settings->get_settings();

The Origami class takes four arguments. The first is the slug of your project. The second is the slug of the tab we want to load by default on the settings page. More on settings tabs in a moment. The third argument is an optional array of modules to load. Current modules include sysinfo and licensing. The fourth argument is an optional string indicating where the settings panel should be displayed. By default, unless passed the value network, this will display panels per site. The network argument will result in a network-wide panel that is displayed in the network admin.

At this point, we now have a global $your_plugin_options containing an array of the available options for your plugin. Of course, we haven't defined any options, so right now it's just a blank array... not very useful!

Adding a settings panel through this library consists of three basic components: Adding the settings themselves, adding settings tabs (grouping settings), and adding a menu item for the settings page. Let's start with adding the settings menu.

Adding A Menu Item

Adding a menu item looks like this (remember, your plugin slug is your-plugin):

function your_plugin_add_menu( $menu ) {
    $menu['page_title'] = __( 'Your Plugin Settings', 'your-plugin' );
    $menu['menu_title'] = __( 'Your Plugin', 'your-plugin' );

    return $menu;
}
add_filter( 'your_plugin_menu', 'your_plugin_add_menu' );

This is about as simple a configuration as you can get for the menu (technically, you can leave those out and use the defaults, but that would just look silly). However, there are several other defaults you can override to configure your menu as you see fit...

function your_plugin_add_menu( $menu ) {
    $menu['type']       = 'submenu';                                    // Can be set to 'submenu' or 'menu'. Defaults to 'menu'.
    $menu['parent']     = 'options-general.php';                        // If 'type' is set to 'submenu', defines the parent menu to place our menu under. Defaults to 'options-general.php'.
    $menu['page_title'] = __( 'Your Plugin Settings', 'your-plugin' );  // The page title. Defaults to 'Origami'.
    $menu['show_title'] = false;                                        // Whether or not to display the title at the top of the page.
    $menu['menu_title'] = __( 'Your Plugin', 'your-plugin' );           // The menu title. Defaults to 'Origami'.
    $menu['capability'] = 'manage_options';                             // The minimum capability required to access the settings panel. Defaults to 'manage_options'.
    $menu['icon']       = '';                                           // An (optional) icon for your menu item. Follows the same standards as the add_menu_page() function in WordPress.
    $menu['position']   = null;                                         // Where in the menu to display our new menu. Defaults to 'null' (bottom of the menu).
    $menu['allow_reset'] = true;                                        // Whether or not to allow users to reset the settings per section.

    return $menu;
}
add_filter( 'your_plugin_menu', 'your_plugin_add_menu' );

That's it! Now that we've added our menu, maybe we should provide some content. Let's start with some tabs:

Adding Settings Tabs

Even if you don't need more than one tab, registering one tab is required (we recommend just calling it 'general'). Here's how:

function your_plugin_settings_tabs( $tabs ) {
    $tabs['general'] = __( 'General', 'your-plugin' );

    return $tabs;
}
add_filter( 'your_plugin_settings_tabs', 'your_plugin_settings_tabs' );

Again, simple. You can add as many tabs as you want through this filter, though if you add too many, the page might look odd!

Adding Settings Sections

Settings sections allow you to create sub-sections in each main tab. This is accomplished like so:

function your_plugin_settings_sections( $sections ) {
    $sections = array(
        'general' => array(
            'main' => __( 'General Settings', 'your-plugin' )
        )
    );

    return $sections;
}
add_filter( 'your_plugin_registered_settings_sections', 'your_plugin_settings_sections' );

Sections are optional, but make sorting through a large settings panel easier!

Defining Unsavable Tabs

In some situations, such as the support tab in the Origami demo, you may not want to display a save button. Preventing saving a tab can be accomplished using the your_plugin_unsavable_tabs filter like this:

function your_plugin_define_unsavable_tabs() {
    $tabs = array( 'support' );

    return $tabs;
}
add_filter( 'your_plugin_unsavable_tabs', 'your_plugin_define_unsavable_tabs' );

Finally, let's populate that tab with some settings:

Adding Settings

There are a lot of possible options in creating your settings, so we're going to keep this super simple and let you read in more detail in the settings reference.

function your_plugin_settings( $settings ) {
    $plugin_settings = array(
        'general' => array(
            'main' => array(
                array(
                    'id'   => 'your_first_setting',
                    'name' => __( 'Your First Setting', 'your-plugin' ),
                    'desc' => __( 'This is your first setting!', 'your-plugin' ),
                    'type' => 'text'
                )
            )
        )
    );

    return array_merge( $settings, $plugin_settings );
}
add_filter( 'your_plugin_registered_settings', 'your_plugin_settings' );

Breaking down the settings array, you can see that it is a multi-dimensional array where each settings tab is a multi-dimensional array, and each setting is an array.

Accessing Settings

So you've added a few settings, now what?

Assuming that when instantiating the settings class, you stored it to a variable we can access as $settings we can retrieve a specific setting like this:

$settings->get_option( 'your_first_setting' );

The get_option() method takes two arguments: key and default. The first argument, key, is mandatory; it is the ID of the setting we want to retrieve. The second argument is optional and specifies a default value to return if the specified key doesn't exist.

That's it! You're all set! Don't forget to read the settings reference for further info on storing and working with settings!