latest version

Customizer

Introduction

Customizer Options {theme}/framework-customizations/theme/options/customizer.php are turned into Customizer elements (panels, sections and controls).

The customizer elements have a strict structure which also applies to options array structure:

  • Containers can be nested only 2 levels

    • container > option is turned into section > control
    • container > container > option is turned into panel > section > control
    • container > container > container > option will not work panel > section > ERROR
  • Containers must contain only options or only containers, because a panel can’t contain both sections and controls.

Examples

Try the below arrays in {theme}/framework-customizations/theme/options/customizer.php.

  • Create a Section

    $options = array(
        'section_1' => array(
            'title' => __('Unyson Section', '{domain}'),
            'options' => array(
    
                'option_1' => array(
                    'type' => 'text',
                    'value' => 'Default Value',
                    'label' => __('Unyson Option', '{domain}'),
                    'desc' => __('Option Description', '{domain}'),
                ),
    
            ),
        ),
    );
    
  • Create a Panel with Sections

    $options = array(
        'panel_1' => array(
            'title' => __('Unyson Panel', '{domain}'),
            'options' => array(
    
                'section_1' => array(
                    'title' => __('Unyson Section #1', '{domain}'),
                    'options' => array(
    
                        'option_1' => array(
                            'type' => 'text',
                            'value' => 'Default Value',
                            'label' => __('Unyson Option #1', '{domain}'),
                            'desc' => __('Option Description', '{domain}'),
                        ),
    
                    ),
                ),
    
                'section_2' => array(
                    'title' => __('Unyson Section #2', '{domain}'),
                    'options' => array(
    
                        'option_2' => array(
                            'type' => 'text',
                            'value' => 'Default Value',
                            'label' => __('Unyson Option #2', '{domain}'),
                            'desc' => __('Option Description', '{domain}'),
                        ),
                        'option_3' => array(
                            'type' => 'text',
                            'value' => 'Default Value',
                            'label' => __('Unyson Option #3', '{domain}'),
                            'desc' => __('Option Description', '{domain}'),
                        ),
    
                    ),
                ),
    
            ),
        ),
    );
    
  • Get option database/saved value in template

    $value = fw_get_db_customizer_option('option_1');
    

Additional Arguments

  • Control arguments can be set in wp-customizer-args option parameter.

    $options = array(
        'section_1' => array(
            'title' => __('Unyson Section', '{domain}'),
            'options' => array(
    
                'option_1' => array(
                    'type' => 'text',
                    'value' => 'Default Value',
                    'label' => __('Unyson Option', '{domain}'),
                    'desc' => __('Option Description', '{domain}'),
    
                    'wp-customizer-args' => array(
                        'priority' => 3,
                    ),
                ),
    
            ),
        ),
    );
    
  • Setting arguments can be set in wp-customizer-setting-args option parameter.

    $options = array(
        'section_1' => array(
            'title' => __('Unyson Section', '{domain}'),
            'options' => array(
    
                'option_1' => array(
                    'type' => 'text',
                    'value' => 'Default Value',
                    'label' => __('Unyson Option', '{domain}'),
                    'desc' => __('Option Description', '{domain}'),
    
                    'wp-customizer-setting-args' => array(
                        'capability' => 'edit_posts',
                    ),
                ),
    
            ),
        ),
    );
    

Live Preview

In background, customizer options are converted into customizer elements, so they follow default WordPress behavior and implementing a live preview can be done using the default WordPress solution.

  1. Change the setting transport and enqueue the javascript

    // file: {theme}/inc/hooks.php
    
    if (defined('FW')):
        /**
         * @param WP_Customize_Manager $wp_customize
         * @internal
         */
        function _action_customizer_live_fw_options($wp_customize) {
            if ($wp_customize->get_setting('fw_options[OPTION_ID]')) {
                $wp_customize->get_setting('fw_options[OPTION_ID]')->transport = 'postMessage';
    
                add_action( 'customize_preview_init', '_action_customizer_live_fw_options_preview' );
            }
        }
        add_action('customize_register', '_action_customizer_live_fw_options');
    
        /**
         * @internal
         */
        function _action_customizer_live_fw_options_preview() {
            wp_enqueue_script(
                'mytheme-customizer',
                get_template_directory_uri() .'/assets/js/theme-customizer.js',
                array( 'jquery','customize-preview' ),
                fw()->theme->manifest->get_version(),
                true
            );
        }
    endif;
    
  2. Handle the change in javascript

    // file: {theme}/assets/js/theme-customizer.js
    
    ( function( $ ) {
        wp.customize( 'fw_options[OPTION_ID]', function( value ) {
            value.bind( function( newval ) {
                /**
                 * An array of collected html inputs
                 * [{'name':'input[name]','value':'input value'}]
                 * or
                 * [{'name':'input[name]','value':'input value'},{'name':'input[name]','value':'input value'},...]
                 */
                newval = JSON.parse(newval);
    
                $( 'h1' ).text( newval[0].value );
            } );
        } );
    } )( jQuery );
    

    Note

    The value comes in [{'name':'input[name]','value':'input value'}] format, because the customizer form is not submitted as a regular form. A control can store its value only inside a single input which has some special attributes (instead of name="...") and it is monitored for changes by the Customizer script to trigger the preview update. Because of that, the framework options collect all their inputs values and store them in that special input (here is an advanced explanation).