Include warning against the use of is_admin in the Customizer section of the Theme Handbook #1529
Labels
developer documentation (DevHub)
Improvements or additions to developer documentation
[Status] To do
Issue marked as Todo
themes
Issues for Theme Developer Handbook
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:
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 whyis_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:
customize_register
hook as well.The text was updated successfully, but these errors were encountered: