Control

Controls are the main Customizer object for building UI fields. Every control must be associated with a setting, and that setting will store user-entered data from the control as well as display and sanitize it in the live preview. Controls must be added to a section before they will be displayed (and sections must contain controls to be displayed).

REMINDER

This is only a brief demonstration of how to create a control using the Customizer API. For additional information about Control, please check the official control documentation.

Demonstration

Here's a demonstration on how to create a control in Handy. We'll utilize textarea control in this demonstration.

 
Handy::control( 'textarea', [
    'id'          => 'textarea_id',
    'section'     => 'layout_section',
    'default'     => '',
    'label'       => esc_html__( 'Textarea Control', 'textdomain' ),
    'description' => esc_html__( 'Description Here', 'textdomain' ),
    'placeholder' => esc_html__( 'Enter Text', 'textdomain' )
    'priority'    => 1
]);

Basic Usage

The only method to retrieve the value of a control is to use the get_theme_mod(). For further details, please check the get_theme_mod() documentation.

 
// Return a string.
$value = get_theme_mod( 'textarea_id' );

Parameters

Name	Description
id	`string` `required` The unique slug like string used as an ID and also as an index name in storing data in a database.
section	`string` `required` The ID of the section in which the control will be displayed.
default	`string` `optional` The predetermined value of the control. Default empty.
label	`string` `optional` The label or title of the control to show in the UI. Default empty.
description	`string` `optional` The description of the control to show in the UI. Default empty.
priority	`integer` `optional` The order of control appears in the section. Default `0`.
validations	`array` `optional` The set of validations used to validate the value of the control. For further details, read validations. Default empty.
active_callback	`callable` `optional` A callback function that determines the visibility of a control, whether to show or hide depending on a condition. For further details, read active_callback. Default empty.
sanitize_callback	`callable` `optional` A callback function that sanitizes the value of control before storing it in the database. Note that this is only optional since each control is already well sanitized. For further details, read sanitize_callback. Default empty.