Adding Customizer Settings

Customizer Settings are added in a similar manner as Metaboxes and Options Pages, but there are some differences. These are described here.

The power of WP Custom Fields and the Customizer is that it adds custom fields such as Typography, Heading and Dimension, extending Customizer Fields.

 

Group Setting Properties

On the highest level, a customizer may have the following properties:

key	type	description
title	string	The title for customizer panel (required)
id	string	The id of customizer settings. This is the key under which the data will be saved. (required)
sections	array	The sections, which each have a group of fields.
option	string	Defines where data is saved. By default, this is saved in the options table as a theme mod. Accepts 'option' or 'theme_mod'. Defaults to 'theme_mod'.
panel	boolean	Whether to group the sections under the main panel or add them to the customizer directly. If panel is not set, or set to false, the sections will be added to the existing customizer screen.

 

Section Properties

These values represent the keys for each section that may be added.

key	type	description
title	string	The title for customizer section (required)
id	string	The id of customizer section (required). Existing ids such as 'themes', 'title_tagline', 'colors', 'header_image', 'background_image' or 'static_front_page' are also accepted to add additional fields to existing customizer sections.
fields	array	The fields under this section
active_callback	string	Reference to a function name which is used to check if this panel should be rendered, such as 'is_page'.

 

Adding Fields

Please note: Customizer Fields have a different structure as fields for Metaboxes or Options Pages and do not support all type of fields.

Common Field Properties

These properties are common for each field.

key	type	description
title	string	The title for the field (required)
id	string	The id of the field (required).
description	string	An optional description for this field.
type	string	The type of field. Supports built-in values such as 'text', 'hidden', 'number', 'range', 'url', 'tel', 'email', 'search', 'time', 'date', 'datetime', 'week' or 'checkbox', 'textarea', 'radio', 'select', 'dropdown-pages'. Also support custom types from WP Custom fields such as 'background-properties', 'colorpicker', 'cropped-image', 'code-editor', 'image', 'media', 'upload', 'textarea', 'dimension', 'typography', 'custom' or 'heading' (required).
selector	string or array	The css selector to style with this field, such as '.site-header'. See the section on custom styling.
transport	string	Determines if updating this field refreshes the whole view, or that values are transferred using custom JS. Accepts 'refresh or 'postMessage (for custom refreshing).
partial	array	Properties for a partial object. A partial allows you to render a component of the customizer front-end and edit this accordingly. See the codex for more information on accepted properties.
sanitize	string	Accepts a function name which is used to sanitize input.
sanitize_js	string	Accepts a function name which is used to sanitize js input.
custom	string	The complete, namespaced reference to a custom class that is rendering a field. Allows to add custom customizer fields.

Additional Field Properties

These properties only apply to some fields.

key	type	description
choices	array	Array of options for a select or radio type of field, such as ['option' => 'Label', 'option_2' => 'Label 2'].
code_type	string	The code type, used in the 'code-editor' field. Supports 'text/css' and 'text/javascript'.
input_attrs	array	Array of input attributes, such as '['min' => 0, 'max' => 10]'
mime_type	string	The allowed mime_type for any 'image', 'media' or 'upload' type.
height	int	Height of a field
width	int	Width of a field

We invite you to play around with the different field types to see what their effect is.

Collapsible Sections

WP Custom Fields allows having collapsible heading within a section. For this, use the heading element.

Pass the IDs of fields you want to hide in the choices attribute. These fields are hidden unless you click the heading. This will show the fields. The following array is an example configuration:

array(
    'default'       => '',
    'id'            => 'some_heading',
    'title'         => __('Collapsible Heading', 'wp-custom-fields'),
    'description'   => __('Just some random description', 'wp-custom-fields'),
    'choices'       => ['id_of_hidden_field', 'another_id_of_hidden_field'],
    'type'          => 'heading',
),

Custom Styling & Refreshing with postMessage

This section is moved to the page CSS Style Output. You'll find everything concerning partial refreshing and customizer fields there.

 

Examples

The following examples show how to actually add customizer sections and panels.

Sections under a Custom Panel

This example puts one section under a custom panel named 'Custom Customizer'.

$fields = MakeitWorkPress\WP_Custom_Fields\Framework::instance();

$fields->add( 'customizer', array(
    'id'            => 'wp_custom_fields_customizer_panel',
    'title'         => __('Custom Customizer', 'wp-custom-fields'),
    'description'   => __('Customizer Panel', 'wp-custom-fields'),
    'panel'         => true,
    'sections'      => array(
        array(
            'id'            => 'first_section_custom',
            'title'         => __('Section One', 'wp-custom-fields'),
            'fields'    => array(                   
                array(
                    'default'       => '',
                    'selector'      => array( 'selector' => '.site-header', 'property' => 'background-color' ),
                    'id'            => 'new_field_value15',
                    'title'         => __('Example Color', 'wp-custom-fields'),
                    'description'   => __('Add an example color', 'wp-custom-fields'),
                    'transport'     => 'postMessage',
                    'type'          => 'colorpicker',
                ),
                array(
                    'choices'       => array('one' => 'ONE', 'two' => 'TWO'),
                    'default'       => '',
                    'id'            => 'new_field_value18',
                    'title'         => __('Example Select', 'wp-custom-fields'),
                    'type'          => 'select',
                ),    
                array(
                    'default'       => '',
                    'selector'      => '.site-header',
                    'id'            => 'new_field_value20',
                    'title'         => __('Example Upload', 'wp-custom-fields'),
                    'type'          => 'image'
                ),              
                array(
                    'default'       => '',
                    'selector'      => 'h2.entry-title',
                    'id'            => 'new_field_value22',
                    'title'         => __('Example Typography', 'wp-custom-fields'),
                    'description'   => __('Example Typography Description', 'wp-custom-fields'),
                    'type'          => 'typography'
                ),
                array(
                    'default'       => '',
                    'selector'      => 'h1',
                    'id'            => 'new_field_value23',
                    'title'         => __('Example Typography', 'wp-custom-fields'),
                    'description'   => __('Example Typography Description', 'wp-custom-fields'),
                    'type'          => 'typography'
                ),                
                array(
                    'default'       => '',
                    'id'            => 'new_field_value24',
                    'title'         => __('Example Textarea', 'wp-custom-fields'),
                    'type'          => 'textarea'
                ),
                array(
                    'default'       => '',
                    'id'            => 'new_field_value28',
                    'title'         => __('Example Heading', 'wp-custom-fields'),
                    'description'   => __('Example Description', 'wp-custom-fields'),
                    'type'          => 'heading'
                ),                
                array(
                    'default'       => '',
                    'id'            => 'new_field_value26',
                    'title'         => __('Example Dimension', 'wp-custom-fields'),
                    'type'          => 'dimension'
                ), 
                array(
                    'default'       => '',
                    'id'            => 'new_field_value27',
                    'title'         => __('Example Checkbox', 'wp-custom-fields'),
                    'type'          => 'checkbox',
                    'input_attrs'   => ['class' => 'switcher']
                )                                                                  
            )              
        )
    )
) );

Adding Fields under an Existing Section

This example adds fields to an existing section, namely the background section which is added by WordPress by default. It also shows how you can add fields that alter the content within the customizer dynamically.

$fields->add( 'customizer', array(
    'id'            => 'wp_custom_fields_customizer_2',
    'title'         => __('Customizer 2', 'wp-custom-fields'),
    'description'   => __('Customizer Panel 2', 'wp-custom-fields'),
    'sections'      => array(
        array(
            'id'            => 'background_image',
            'title'         => __('Section Two', 'wp-custom-fields'),
            'fields'    => array(                   
                array(
                    'default'       => '',
                    'selector'      => array( 'selector' => '.site-header', 'property' => 'background-color' ),
                    'id'            => 'new_field_value26',
                    'title'         => __('Example Color', 'wp-custom-fields'),
                    'description'   => __('Add an example color', 'wp-custom-fields'),
                    'transport'     => 'postMessage',
                    'type'          => 'colorpicker'
                ),
                array(
                    'choices'       => array('one' => 'ONE', 'two' => 'TWO'),
                    'default'       => '',
                    'id'            => 'new_field_value28',
                    'title'         => __('Example Select', 'wp-custom-fields'),
                    'type'          => 'select'
                ),
                array(
                    'selector'      => array( 'selector' => '.copyright', 'html' => true ),
                    'default'       => '',
                    'id'            => 'new_field_value34',
                    'title'         => __('Example HTML Input', 'wp-custom-fields'),
                    'type'          => 'text',
                    'transport'     => 'postMessage'
                ),                     
                array(
                    'default'       => '',
                    'selector'      => '.site-header',
                    'id'            => 'new_field_value30',
                    'title'         => __('Example Image', 'wp-custom-fields'),
                    'type'          => 'image'
                ),
                array(
                    'default'       => '',
                    'selector'      => 'h2.entry-title',
                    'id'            => 'new_field_value32',
                    'title'         => __('Example Typography', 'wp-custom-fields'),
                    'description'   => __('Example Typography Description', 'wp-custom-fields'),
                    'type'          => 'typography'
                )                
            )              
        )
    )
) );