-
Notifications
You must be signed in to change notification settings - Fork 16
Adding Customizer Settings
Michiel Tramper edited this page Mar 28, 2018
·
17 revisions
Customizer Settings are added in a similar manner as Metaboxes and Options Pages, but there are some differences.
| 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. |
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'. |
Customizer Fields have a different array structure as fields for Metaboxes or Options Pages and do not support all type of fields.
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 | array | 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 'colorpicker', 'cropped-image', 'image', 'media', 'upload', 'textarea', 'dimension', 'typography', 'custom' or ``''heading': |
| '``. | ||
| 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. |
These properties only apply to some fields.
| key | type | description |
|---|---|---|
| choices | array | Array of options for a select field, such as ['option' => 'Label', 'option_2' => 'Label 2']; |
| 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.
WP Custom Fields allows to transfer the values of field to custom styling.
It also has some built-in functions to refresh the customizer partially. It allows to dynamically add content or styling without a full refresh of the customizer preview window.
For now, this is supported for textual content and color picker fields. This is done by setting the 'postMessage' property of a field to 'postMessage'.
The following example of a field array changes the background colour of the element with the class 'header' while using the customizer.
array(
'default' => '',
'selector' => array( 'selector' => '.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',
),The following example of a field array inserts the content in the element with the class 'copyright', while using the customizer.
array(
'default' => '',
'selector' => array( 'selector' => '.copyright', 'html' => true ),
'id' => 'new_field_value27',
'title' => __('Example Content', 'wp-custom-fields'),
'transport' => 'postMessage',
'type' => 'textarea',
),If selector is not a string, it accepts the following properties:
| key | type | description |
|---|---|---|
| selector | string | The selector, such as '.site-header'. |
| property | string | A custom property to style, such as 'background-color'. |
| html | boolean | Whether to output the values of a given field as html to the given selector. |
| attr | string | The name of a custrom attribute of to which you want to add the customizer field value. This allows to change attributes such as 'href' using partial refresh with 'postMessage' |
If the selector key is a string
The following examples show how to actually add customizer sections and panels.
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']
)
)
)
)
) );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'
)
)
)
)
) );WP Custom Fields has been developed by Make it WorkPress