Tutorial on: Building Settings Pages with Piklist

Creating WordPress Settings pages with Piklist is as easy as creating any other field type. First we register the Settings Page, and then we start adding Settings Sections. Piklist uses the standard WordPress settings API, plus it adds extra power and ease of use. You can use any Piklist field type on a Settings page, and easily add Tabs as well.

In this tutorial, we will create a Settings Page that includes three fields: SELECT, TEXT and COLORPICKER:

Register your Settings Page

Like everything in Piklist, we start with a simple but powerful array. Then we hook it to the proper Piklist function. If you’re creating this settings page in your theme then this code belongs in FUNCTIONS.PHP. If this is a Settings Page for a Plugin, then add it to the main file in you Plugin, after you register your plugin with Piklist.

  add_filter('piklist_admin_pages', 'piklist_theme_setting_pages');
  function piklist_theme_setting_pages($pages)
  {
    $pages[] = array(
      'page_title'  => 'Theme Settings'       // Title of page
      ,'menu_title' => 'Theme Settings'       // Title of menu link
      ,'sub_menu'   => 'themes.php'           // Show this page under the THEMES menu 
      ,'capability' => 'manage_options'       // Minimum capability to see this page
      ,'menu_slug'  => 'piklist-theme-fields' // Menu slug
      ,'setting'    => 'piklist-theme'        // The settings name
      ,'icon'       => 'options-general'      // Menu/Page Icon
      ,'save'       => true                   // true = show save button / false = hide save button
    );

    return $pages;
  }

Create a Settings Section

Now we need to create the proper folder structure in your theme. Piklist uses this folder structure to automatically help you when building fields. Create a piklist folder, and then a parts subfolder, and then add a settings subfolder. You can see the supported Piklist folder structure here.
Each file we add to the the settings folder will create a Settings Section on the Settings Page. You can have multiple Sections on each Settings Page as well. Each field we include in this file will be part of this Section. Fairly straight forward. Ok, let’s create our Settings Section file!
Create a new file: let’s call it demo-settings.php. At the top of the file, we will add a comment block that will control the configuration of the Settings Section. This comment block is very similar to what you would see in a standard WordPress plugin or theme. Here are the minimum variables required:
```
<?php
/*
Title: Theme Settings Section
Setting: piklist-theme
*/
```
This comment block tells Piklist you want to name your Settings Section, “My Demo Settings Section”, and you want to associate this Section with the Settings Page that uses the setting “demo-setting”. When you registered your Settings Page, earlier in this tutuorial, this is the setting you defined. The Piklist comment block for settings supports a lot more than just these two variables. You can view the full list in our docs.

Now, let’s create our first field, a TEXT BOX:

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

This simple array will create a TEXT BOX that automatically uses the WordPress settings API to display and save. The type=>text variable tells Piklist what sort of field to render. Also, notice that this is very similar to the way you create fields for meta-boxes.

Now, let’s create our select field, a SELECT FIELD:

  piklist('field', array(
    'type' => 'select'
    ,'field' => 'select'
    ,'label' => 'Select Box'
    ,'description' => 'Choose from the drop-down.'
    ,'attributes' => array(
      'class' => 'text'
    )
    ,'choices' => array(
      'option1' => 'Option 1'
      ,'option2' => 'Option 2'
      ,'option3' => 'Option 3'
    )
  ));

Notice that this array is very similar to the one used to create the TEXT BOX. Just two differences:

type => select: Tells Piklist that you want to render a SELECT field.
The choices array adds your choices.

That’s it! Everything else is the same.

One more field to go in this tutorial. Let’s create our COLORPICKER field. Normally, you would need to add Javascript and CSS to create this field… but not with Piklist!

  piklist('field', array(
    'type' => 'colorpicker'
    ,'field' => 'colorpicker'
    ,'label' => 'Choose a color'
    ,'value' => '#aee029'
    ,'description' => 'Click in the box to select a color.'
    ,'attributes' => array(
      'class' => 'text'
    )
  ));

Seriously, that’s all you need to create a COLORPICKER field. You will notice this is pretty much the same code used to create the TEXT BOX, except we set ‘type’ => ‘colorpicker’.

You new Settings Page should look like this:

Full Code Snippet for Settings Section:

<?php
/*
Title: Theme Settings Section
Setting: piklist-theme
*/
piklist('field', array(
    'type' => 'text'
    ,'field' => 'text'
    ,'label' => 'Text Box'
    ,'description' => 'Field Description'
    ,'value' => 'Default text'
    ,'attributes' => array(
      'class' => 'text'
    )
  ));
piklist('field', array(
    'type' => 'select'
    ,'field' => 'select'
    ,'label' => 'Select Box'
    ,'description' => 'Choose from the drop-down.'
    ,'attributes' => array(
      'class' => 'text'
    )
    ,'choices' => array(
      'option1' => 'Option 1'
      ,'option2' => 'Option 2'
      ,'option3' => 'Option 3'
    )
  ));
piklist('field', array(
    'type' => 'colorpicker'
    ,'field' => 'colorpicker'
    ,'label' => 'Choose a color'
    ,'value' => '#aee029'
    ,'description' => 'Click in the box to select a color.'
    ,'attributes' => array(
      'class' => 'text'
    )
  ));

Using these fields in a theme:

Where possible, Piklist uses the default WordPress functions to get things done, and using Settings is no different. You can use the get_option function to pull this data into your theme. Here’s how you would use these fields in your theme file:

<?php
  $theme_options = get_option('piklist-theme');

  $text_field = $theme_options['text'];
  $select_field = $theme_options['select'];
  $colorpicker_field = $theme_options['colorpicker'];

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


?>