Customizer_register not saving custom setting to database

Question

I'm currently trying to work on a WordPress theme based on Sage. The stage I'm at is creating custom controls to display on the customize screen for WordPress where you typically change things like the site title or theme colors if you're an end user.

It seems that the new setting I'm trying to add with add_setting isn't actually creating a database entry (Calling get_theme_mod on that particular setting returns nothing). I'm thinking that it has something to do with the add_control method but I've checked the WordPress Documentation on this and I have it matching as far I can tell.

namespace Roots\Sage\Customizer;

use Roots\Sage\Assets;

/**
 * Add customization settings for the theme
 */
function customize_register($wp_customize) {
  //////////////////////////
  // WIDGET STYLE OPTIONS //
  //////////////////////////
  $wp_customize->add_section( 'widget_style_section', array(
     'title'  => __('Widget Styling', __NAMESPACE__),
     'priority' => 115,
  ));

  $wp_customize->add_setting( 'widget_list_style', array(
     'default' => 'hide',
     'transport' => 'postMessage',
  ));

  $wp_customize->add_control( 'widget_list_style_control', array(
      'label' => __( 'Display List Style?', __NAMESPACE__),
      'Description' => __('Removes the symbols next to bulleted and    unbulleted lists in Widgets', __NAMESPACE__),
      'section' => 'widget_style_section',
      'settings' => 'widget_list_style',
      'type'    => 'radio', // TODO: CONTROL IS CONFUSED ABOUT WHAT TYPE IT IS, THATS WHY NO REFRESH
      'choices' => array(
           'hide' => __('Hide'),
           'show' => __('Show'),
       ),
  ));

  // Add postMessage support
  $wp_customize->get_setting('blogname')->transport = 'postMessage';
  $wp_customize->get_setting('blogdescription')->transport = 'postMessage';

  // TEST - To see if widget_list_style is storing properly
  echo get_theme_mod('widget_list_style');
}

add_action('customize_register', __NAMESPACE__ . '\\customize_register');

Answer 1

The problem with the code sample is that the setting is using widget_ as the prefix. This is a reserved prefix for widgets, per the customizer handbook:

Important: Do not use a setting ID that looks like widget_*, sidebars_widgets[*], nav_menu[*], or nav_menu_item[*]. These setting ID patterns are reserved for widget instances, sidebars, nav menus, and nav menu items respectively. If you need to use “widget” in your setting ID, use it as a suffix instead of a prefix, for example “homepage_widget”.

Here is the modified code which works as expected:

<?php

namespace Roots\Sage\Customizer;

use Roots\Sage\Assets;

/**
 * Add customization settings for the theme
 */
function customize_register($wp_customize) {
    //////////////////////////
    // WIDGET STYLE OPTIONS //
    //////////////////////////
    $wp_customize->add_section( 'style_section_widget', array(
        'title'  => __('Widget Styling', __NAMESPACE__),
        'priority' => 115,
    ));

    $wp_customize->add_setting( 'list_style_widget', array(
        'default' => 'hide',
        'transport' => 'postMessage',
    ));

    $wp_customize->add_control( 'widget_list_style_control', array(
        'label' => __( 'Display List Style?', __NAMESPACE__),
        'Description' => __('Removes the symbols next to bulleted and    unbulleted lists in Widgets', __NAMESPACE__),
        'section' => 'style_section_widget',
        'settings' => 'list_style_widget',
        'type'    => 'radio',
        'choices' => array(
            'hide' => __('Hide'),
            'show' => __('Show'),
        ),
    ));

    // Add postMessage support
    $wp_customize->get_setting('blogname')->transport = 'postMessage';
    $wp_customize->get_setting('blogdescription')->transport = 'postMessage';
}

add_action('customize_register', __NAMESPACE__ . '\\customize_register', 11);

Note also that I changed the priority for customize_register from 10 (the default) to 11 since the blogname and blogdescription settings may not be registered at that point.

Answer 2

From Theme_Customization_API:
To add your own options to the customizer, you need to use a minimum of 2 hooks:

customize_register
This hook allows you define new customizer panels, sections, settings, and controls.

wp_head
This hook allows you to output custom-generated CSS so that your changes show up correctly on the live website.

So your customize_register action look like(replace your theme name with mytheme):

function mytheme_customize_register( $wp_customize ) {
   //All our sections, settings, and controls will be added here
}
add_action( 'customize_register', 'mytheme_customize_register' );

Next, you need to define your settings, then your sections, then your controls (controls need a section and a setting to function).

Note: Only set this to 'postMessage' if you are writing custom Javascript to control the Theme Customizer's live preview.