Issue Description

The Theme Handbook was the first hit for me on a search for information on how to use the Customizer API, and while trying to follow the information on that page I lost 8 hours to an infuriating problem where the section I was adding would appear but then disappear again after about a second. Online searches turned up lots of other people having the same issue, but no explanation on why they were having the issue or how they resolved it. I eventually stumbled on the Codex page for the Customizer and found this comment:

Important: Do not conditionally load your Customizer code with an is_admin() check. If you only add your customize_register if is_admin(), then any panels, sections, or controls will be unavailable when the Customizer preview loads. As of WordPress 4.1, there are contextual panels, sections, and controls so that they can be displayed only on certain URLs being previewed. If you only register your panels, sections, and controls if is_admin() then you'll be effectively saying that these are not contextual to any URL on your site. For more information, see #30387 and #29758.

URL of the Page with the Issue

https://developer.wordpress.org/themes/customize-api/customizer-objects/

Section of Page with the issue

Customizer Objects

Why is this a problem?

Developers instinctively include code meant only for the admin screens behind a conditional is_admin() check — it's standard practice. It's unintuitive to not do that when working with the Customizer, and unintuitive things should be documented. It makes perfect sense why is_admin() is bad in this context when you know about it, but since that call might not happen in the vicinity of the Customizer code it might not be something developers think to adjust while debugging.

It's enough of a problem that the comment was added to the Codex after various tickets were opened asking why custom sections were vanishing from the Customizer. But if a developer doesn't find the Codex Customizer API docs then they won't see that comment. Even if they do they might first waste 8 hours of their life hunting for the problem in their code.

Suggested Fix

I propose:

1. Copying the comment on the Codex and adding either immediately before or after the first code sample on the Theme Handbook / Customizer API page. e.g.

function themeslug_customize_register( $wp_customize ) {
  // Do stuff with $wp_customize, the WP_Customize_Manager object.
}
add_action( 'customize_register', 'themeslug_customize_register' );

Important: Do not conditionally load your Customizer code with an is_admin() check. If you only add your customize_register if is_admin(), then any panels, sections, or controls will be unavailable when the Customizer preview loads. As of WordPress 4.1, there are contextual panels, sections, and controls so that they can be displayed only on certain URLs being previewed. If you only register your panels, sections, and controls if is_admin() then you'll be effectively saying that these are not contextual to any URL on your site. For more information, see #30387 and #29758.

The Customizer Manager provides add_, get_, and remove_ methods for each Customizer object type; each works with an id. The get_ methods allow for direct modification of parameters specified when adding a control.

2. Making mention of this on the HelpHub page for the customize_register hook as well.