WordPress Customizer API

We recently had the pleasure of giving a talk about WordPress Customizer at the 4th WordPress Meetup in Zagreb. We explained why you should use it and how to add own options, panels, sections and controls. In order to keep a promise we gave at the talk, this WordPress Customizer post series provides further details.

This themed WordPress Customizer was announced in 2012 in WordPress 3.4 version. It gives administrators the opportunity of changing theme settings and being able to see the effect those changes have on the theme. Equally visitors won’t see the changes until the administrator saves them. WordPress Customizer has been given a re-branding in WordPress 4.0. It’s no longer made only for theme options, but for the entire WordPress options. It was also given panels which are a new way of dividing controls and sections.

Live Preview

If the theme uses a classic custom page for theme options, the administrator must install and activate that theme in order to check how it works with the content and to check certain theme settings. After that, the administrator needs to check how the theme functions with the web page. WordPress Customizer offers the option of not having to activate the theme in order to check if it fits the webpage content. The administrator can install the theme, change its settings and check the preview of his website with that theme and adjusted settings.

vs. Theme Options

WordPress Customizer makes changing options easier. This is because the administrator doesn’t need to refresh the website with each change, but rather all the changes can be seen in the preview window.

How to adjust WordPress Customizer to your theme?

Like every other WordPress API, Customize API is very simple to use. Everything that will be added to Customizer needs to be defined in the function that will be called to ‘customize_register’ action.

Example:

Action ‘customize_register’ will give our function an access to WP_Customize_Manager object through $wp_customize attribute. WP_Customize_Manager object is made of set of methods for options, panels, sections and control manipulation.

Settings

In order to manipulate settings, WP_Customize_Manager object gives us:

• ::add_setting( $id, $args ) – Add a customize setting.
• ::get_setting( $id ) – Retrieve a customize setting.
• ::remove_setting( $id ) – Remove a customize setting.

• $id – Setting id.
• $args – Setting arguments
  • type – Should Customizer use theme_mod or option functions for calling and setting the option.
  • capability – Capability required to edit this setting.
  • theme_supports – Enable or disable this setting based on whether the theme supports a particular feature.
  • default – Default value of this setting.
  • transport – If you set this option as refresh, the Customizer will refresh preview so that your option changes can be seen. If you set it as postMessage, you can change your option with JavaScript Customizer API. Some options are set as refresh by default and we’ve just shown you how to change that in the upper example.
  • sanitize_callback – The name of the function that will be called to sanitize the input data before saving it to the database.
  • sanitize_js_callback – The name of the function that will be called to sanitize the coming from the database on its way to the theme customizer.

Example:

Panels

Customizer has given us a new way to group sections since WordPress 4.0- the panels. Just like with options, WP_Customizer_Manager object gives us a few methods for panel manipulation.

• ::add_panel( $id, $args ) – Add a customize panel.
• ::get_panel( $id ) – Retrieve a customize panel.
• ::remove_panel( $id ) – Remove a customize panel.

• $id – Panel id or object of WP_Customize_Panel class or has WP_Customize_Panel class as one of its parents.
• $args – Panel arguments
  • priority – Priority of this panel, defining the display order of panels and sections. Lower numbers come first. Default: 160.
  • capability – Capability required for this panel. Default: ‘edit_theme_options’
  • theme_supports – Show or hide this panel based on whether the theme supports a particular feature.
  • title – Title of this panel to show in UI.
  • description – Description of this panel to show in the UI.

Example:

Sections

Customizer offers us control grouping through sections. Just like with options and panels, WP_Customizer_Manager object offers us methods for section manipulation.

• ::add_section( $id, $args ) – Add a customize section.
• ::get_section( $id ) – Retrieve a customize section.
• ::remove_section( $id ) – Remove a customize section.

• $id – Section id or object of WP_Customize_Section class or has WP_Customize_Section class as one of its parents.
• $args – Section arguments
  • priority – Priority of this section, defining the display order of sections. Lower numbers come first. Default: 160.
  • panel – Panel in which to show this section, making it a sub-section.
  • capability – Capability required for this section. Default: ‘edit_theme_options’
  • theme_supports – Show or hide this section based on whether the theme supports a particular feature.
  • title – Title of this section to show in UI.
  • description – Description of this section to show in the UI.

Example:

Controls

Control is actually an object that takes care of how certain option changes. Just like with options, panels and sections, WP_Customizer_Manager object offers us methods for control manipulation.

• ::add_control( $id, $args ) – Add a customize control.
• ::get_control( $id ) – Retrieve a customize control.
• ::remove_control( $id ) – Remove a customize control.

• $id – Control id or object of WP_Customize_Control class or has WP_Customize_Control class as one of its parents.
• $args – Control arguments
  • settings – All settings tied to this control.
  • setting – The primary setting for this control (if there is one).
  • priority – Priority of this control, defining the display order of controls. Lower numbers come first. Default: 10.
  • section – Section where this control will be placed.
  • label – Label of this control to show in UI.
  • description – Description of this control to show in the UI.
  • choices – If type of this control is select or radio, this argument specifies the list of options to be displayed.
  • input_attrs – The custom attributes for this control’s input element.
  • type – Input types text, checkbox, textarea, radio, select, dropdown-pages, email, url, number, hidden and date are supported. Default: text

Example:

Display custom theme setting in template

In order to show the value of the option we added to Customizer, the function get_theme_mod/get_option (relative to type argument options) needs to be called. The function is_customize_preview can be used since WordPress 4.0 version and it returns true or false, depending on whether it was started from Customizer preview or not.

Example:

Show live preview of your settings

Customizer gives us JavaScript API so that we can manipulate options. In the example below, we’ll demonstrate how to bind an event that will execute after the option change.

Example:

Conclusion

WordPress Customizer API is as simple to use as any other WordPress API. It gives developers a standardized approach to solving problems related to theme options, while offering nice and adjusted UI to administrators so theme options can be easily edited. Just like the WordPress philosophy says, Decisions, not Options, we should not overdo because it will slow our preview and website. In the next blog post, we’ll explain how to build custom control.