Use Piklist to Add Settings Options to a WordPress Theme or Plugin

This article continues the earlier introduction to the Piklist developer plugin and focuses on one practical use case: adding settings options to a WordPress theme or plugin. Piklist builds on top of the standard WordPress Settings API, but makes common tasks easier and cleaner.

The general workflow is to register a settings page first, then create one or more settings sections and fields.

Start by registering a settings page. As with many other Piklist features, the setup is mostly just a configuration array added through a filter.

add_filter('piklist_admin_pages', 'piklist_theme_setting_pages');

function piklist_theme_setting_pages($pages) {
    $pages[] = array(
        'page_title' => __('Custom Settings'),
        'menu_title' => __('Settings', 'piklist'),
        'sub_menu'   => 'themes.php',
        'capability' => 'manage_options',
        'menu_slug'  => 'demo-setting',
    );

    return $pages;
}

Create the settings section

Now create the folder structure Piklist expects. It automatically reads settings definitions from a path like:

your-theme/piklist/parts/settings/your-settings-file.php

Each file in that folder becomes a settings section. A single settings page can contain multiple sections.

Create a settings definition file such as demo-settings.php

At the top of the file, add a PHP comment block that tells Piklist how to register the section:

<?php
/*
Title: Theme Settings
Setting: demo-setting
*/

This tells Piklist that the section should be called “Theme Settings” and attached to the demo-setting settings page.

Create a text field

piklist('field', array(
    'type'        => 'text',
    'field'       => 'text',
    'label'       => 'Text Box',
    'description' => 'Field Description',
    'help'        => 'This is help text.',
    'value'       => 'Default text',
    'attributes'  => array(
        'class' => 'text',
    ),
));

Piklist uses the array above to generate a text input through the standard WordPress Settings API. The structure is simple and readable, which makes it easier to guess how to build other field types as well.

A complete settings section example

/*
Title: Theme Settings
Setting: demo_settings
*/

piklist('field', array(
    'type'        => 'text',
    'field'       => 'text',
    'label'       => 'Text Box',
    'description' => 'Text box description',
    'help'        => 'Help text',
    'value'       => 'Default text',
    'attributes'  => array(
        'class' => 'text',
    ),
));

Read the option values inside your theme

Because Piklist uses the normal WordPress Settings API underneath, you can retrieve saved values through the standard Option API:

$theme_options = get_option('my_theme_settings');
$text_field = $theme_options['text'];
$select_field = $theme_options['select'];
$colorpicker_field = $theme_options['colorpicker'];

echo 'This is a text field: ' . $text_field;

That combination of a cleaner definition format and standard WordPress storage is one of the reasons Piklist can be so practical for theme and plugin development.