{"id":4337,"date":"2017-12-16T17:30:30","date_gmt":"2017-12-16T16:30:30","guid":{"rendered":"https:\/\/florianbrinkmann.com\/en\/?p=4337"},"modified":"2020-02-09T10:59:40","modified_gmt":"2020-02-09T09:59:40","slug":"panels-sections-controls-customize-js-api","status":"publish","type":"post","link":"https:\/\/florianbrinkmann.com\/en\/panels-sections-controls-customize-js-api-4337\/","title":{"rendered":"Creating panels, sections, and controls with the Customize JS API"},"content":{"rendered":"

Until now I mostly used the PHP API of the customizer. Since Weston Ruter\u2019s post about the improvements of the Customize JS API in WordPress 4.9<\/a>, I wanted to change that and learn more about the Customize JS API. This post shows you how to create panels, sections, and controls with that API.<\/p>\n\n\n\n\n\n\n\n

Why the Customize JS API has advantages against the PHP API<\/h2>\n\n\n\n

I did not think about that much \u2013 I began with the PHP API and stayed with it. But the PHP API is \u2013 like Weston writes in his post \u2013 just a wrapper for the JS API. He also writes:<\/p>\n\n\n\n

\u00bbThe point here is that in order for the Customizer to scale, the JavaScript API must be used directly. So this is why the Customizer JS API improvements in 4.9 are important as they fix many longstanding annoyances and shortcomings with the JS API.\u00ab<\/p>

Weston Ruter in Improvements to the Customize JS API in 4.9<\/a><\/cite><\/p>Weston Ruter in Improvements to the Customize JS API in 4.9<\/a><\/cite><\/blockquote>\n\n\n\n

So I thought to myself, I will try it out at the next opportunity. And because my Hannover and Bornholm themes need a visual and technical update, I already had it.<\/p>\n\n\n\n

Disadvantage of the Customize JS API<\/h2>\n\n\n\n

There is also a disadvantage of the Customize JS API: currently, it is not very well documented, so it takes some time to find information, even if the API is entirely written in one (or just some) core files, so theoretically one could extract its functioning from there. For me, that was just a little help.<\/p>\n\n\n\n

More helpful was Google, and frequently appearing answers and posts from Weston Ruter \ud83d\ude42<\/p>\n\n\n\n

But now let us come to the main topic of this post:<\/p>\n\n\n\n

Creating panels, sections, and controls with the JS API<\/h2>\n\n\n\n

At first, we need to enqueue a JS file into the customizer\u2019s control area. For that we use the following code:<\/p>\n\n\n

\/\/ Include scripts into the customizer.<\/span>\nadd_action( 'customize_controls_enqueue_scripts'<\/span>, 'hannover_customizer_controls_script'<\/span> );\n\n\/**\n * Prints styles inside the customizer view.\n *\/<\/span>\nfunction<\/span> hannover_customizer_controls_script<\/span>(<\/span>) <\/span>{\n\t\/\/ Add script control section.<\/span>\n\twp_enqueue_script( 'hannover-customize-controls'<\/span>, get_theme_file_uri( 'assets\/js\/customize-controls.js'<\/span> ), [], null<\/span>, true<\/span> );\n}<\/code><\/div>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Now we create the customize-controls.js<\/code> in the assets\/js<\/code> folder with the following content:<\/p>\n\n\n
\/**\n * Custom JavaScript functions for the customizer controls.\n *\n * @version<\/span> 2.0.0\n *\n * @package<\/span> Hannover\n *\/<\/span>\n;(function<\/span> (api)<\/span> <\/span>{\n\tapi.bind('ready'<\/span>, function<\/span> ()<\/span> <\/span>{\n\t\t\/\/ Create theme options panel.<\/span>\n\t\tapi.panel.add(\n\t\t\tnew<\/span> api.Panel('hannover_theme_options'<\/span>, {\n\t\t\t\ttitle: 'Theme Options'<\/span>,\n\t\t\t})\n\t\t);\n\n\t\t\/\/ Add section.<\/span>\n\t\tapi.section.add(\n\t\t\tnew<\/span> api.Section('hannover_example_section'<\/span>, {\n\t\t\t\ttitle: 'Example Section'<\/span>,\n\t\t\t\tpanel: 'hannover_theme_options'<\/span>,\n\t\t\t\tcustomizeAction: 'Customizing \u25b8 Theme Options'<\/span>\n\t\t\t})\n\t\t);\n\n\t\t\/\/ Add checkbox control.<\/span>\n\t\tapi.control.add(\n\t\t\tnew<\/span> api.Control('hannover_example_control'<\/span>, {\n\t\t\t\tsetting: 'hannover_example_setting'<\/span>,\n\t\t\t\ttype: 'checkbox'<\/span>,\n\t\t\t\tsection: 'hannover_example_section'<\/span>,\n\t\t\t\tlabel: 'Check this box to do something.'<\/span>\n\t\t\t})\n\t\t);\n\t});\n})(wp.customize);\n<\/code><\/div>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
We wait until the Customizer is ready and add a panel, section, and control. You can see that the code for adding each of the elements is quite similar. The first parameter of the new call is the ID, after that, there comes an object with the options, like known from the PHP API.<\/p>\n\n\n\n
One exception from that: customizeAction<\/code> for new api.Section<\/code> defines the string that is shown above the title in the section view:<\/p>\n\n\n\n