Cancel

Sarah Gooding

WordPress Theme Developer Handbook Updated with Comprehensive Guide to the Customizer API

photo credit: Artist's Room - (license)
photo credit: Artist’s Room – (license)

The Theme Review Team’s controversial decision to require the use of the Customizer API for building theme options unearthed a wave of criticism and concern about the capabilities of the customizer.

In response to more than 150 comments debating on the topic, Nick Halsey, who has worked extensively on the feature in WordPress core, stopped by to offer a few words in support of the Theme Review Team’s decision:

Many of the comments here are misinformed or unaware of both the full power of and the future importance of the Customizer. I’ve given an overview of my perspective on my blog, and while those views don’t directly represent the views of the WordPress project, I can say that most people working on the Customizer in core would agree with my points. Like it or not, the Customizer is here to stay, and ignoring that fact will eventually cause users to turn against you.

Halsey’s post calls for theme developers to re-examine their philosophies when it comes to building complex UI options and stop re-inventing the wheel. He believes the customizer has more creative potential than developers give it credit for.

Complaints about the amount of screen real estate available and the 300px default width show a lack of creativity and resistance for the sake of resistance to change. Start by removing all of the ads, external links, unnecessary branding, unnecessary options, and general clutter. Make your options self-explanatory – if you need a paragraph to describe what it does, it probably shouldn’t be a user-facing option. Do you still have so much UI that the experience is completely unusable? Try an outside-the-box solution, like utilizing the core media modal (header images and core media controls use it), a custom modal (theme details modal in core), or a slide-out panel (widgets in core and eventually menus in core as well).

Prior to the Theme Review Team’s decision, documentation on theme development with the Customizer API was sparse and claims about its wide range of capabilities were difficult to support.

Resistance from theme developers has WordPress.org contributors scrambling to produce better documentation for using the customizer in themes. Over the weekend, Halsey created a canonical developer tutorial on the Customizer API in the official theme developer handbook.

customizer-api-documentation

This official comprehensive guide includes the following sections and provides detailed examples for each:

Theme Review Team admin Justin Tadlock posted more details clarifying the new WordPress.org guideline and included a list of additional resources for learning more about the customizer.

Over the weekend, Samuel “Otto” Wood, who has written several customizer articles over the years, wrote a “What’s new with the Customizer” tutorial that explores some of its newer features in depth, including panels, active callbacks, and customizing the customizer.

With WordPress 4.3 blazing forward on customizer improvements, now is the time for theme developers to familiarize themselves with the available documentation and tutorials in order to be ready to take full advantage of WordPress’ core-supported method of providing live previews to users.

Category:
Tags:
12

12 responses to “WordPress Theme Developer Handbook Updated with Comprehensive Guide to the Customizer API”

    • Agreed. One of the problems with WordPress has always been the lack of documentation. New features are added regularly and developers are left to guess how to use them. One of such examples is the 3.5 media modal, which has no proper documentation yet, apart from some comments in the code itself.

      Create forum topic from comment

        • Ummmm….

          I hope the WP.Core realizes that one of the BIGGEST reasons that WordPress got a significant leg up on Jooml’r is documentation. I cannot BEGIN to tell you how many Jooml’r developers “jumped ship” because the people writing code were not documenting and I dont mean PHPDoc. In industry its pretty much mandatory.

          I’d got in a significant blowout with J!.Core abut this. I am a experienced programmer, 35+ years of it. Many (many) folks in their forums were asking about documentation months and months after J! MVC came to be. Mostly they heard silence back. We were doing some work, asked about some documentation. They then turned around and asked me if I wanted to document their code. I went, “Uhhh… Are you guys serious?” and they were.

          Imagine working at Microsoft and not documenting work. Visual studio function is METICULOUSLY documented. This is PART of writing software when other developers are to use it. Imagine if PHP were not documented or mySQL or Apache or Linux. This is simply not optional stuff. I dont like it any more than any other software engineer. I prefer to be writing code and not documenting my work. But, thats not optional.

          Standards. Hmmm…

          So, we want standardization of theme’s using Customizer but the folks that author it dont do their standard work in creating it? I would HIGHLY encourage WP.Core to let any developers know that are working on WP.Core function that they simply MUST document their work or they MUST have someone in place as they produce production code to do so or it wont become production code.

          I mean really… Adobe never documented Flash? Acrobat? Google never documented Android? Or Apples iOS? This is part of writing code. Its not just PHPDOC’n parameters in /output out and brief function. Its not fun but its the deal.

          Imagine people using DOVY’s framework and him saying, “Well… I wrote it but I expect all of you using it to document it”. I mean, what are we saying here, a guy that makes a theme framework is being more responsible than those making the application functions?

          While I appreciate the fact a new customizer documentation is now in place thats due to “chineese fire drill” apparently. “How can developers port themes into customizer if they have no good documentation, so we better make that happen”.

          Uhhh… maybe theme developers would not have had any of this happen at all or the TMT be deluged with themes not using customizer if proper documentation were in place from word go.

          If WP wants secure plugins, secure themes, best practices, all these things to be a reality then documentation is how that occurs and the responsibility to product it is the programmers. Thats basic college software engineering.

          Lets go to Microsoft or eBay or Adobe or Google and say, “I want a programmers job. I am a good programmer. But, I dont do documentation”.

          I could be the best programmer on the planet and I’d be shown the door.

          Create forum topic from comment

          • Not trying to be a weener here,

            I appreciate the hard work in getting the documentation you folks worked on in place.

            But, its also an opportunity for the TMT who authored these docs to send a message. That message being, “When WP coding is done, document it” and then developers can work with current information and make better software and wordpress becomes a better tool.

            Create forum topic from comment

          • On the other hand, we can sit here, write essays about who should be writing documentation, and not get anything done at all. How about we take the route of getting more volunteers involved with core?

            Nevertheless, the Customizer API has been documented. It’s just now better documented, which is awesome! I still encourage more people to get involved with writing tutorials and documentation. Writing about a subject is actually a great way to learn more about it.

            Also, TRT (not TMT) didn’t author this documentation. Although, some people involved with the team have written tutorials on the subject in the past.

            Create forum topic from comment

  4. I’m a bit jealous for the developers who will get all about Customizer API in a single place (just kidding)- great work done with the docs.

    I had to learn all of it by looking at code (actually that’s the best way)- I wish to join the team to give my hands on things, hopefully soon.

    Create forum topic from comment

You may also like

Newsletter

Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.