Take the 2-minute tour ×
WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. It's 100% free, no registration required.

When would it be appropriate to use the settings API, and when would it be better to use the theme customizer?

Having Googled around all morning, I haven't been able to find any well considered and recent guidance on this matter. While it's still early to say, I feel that the theme customizer is a suggestive first step towards bringing in more Squarespace-like editing features. Does anyone know of any plans to sunset the settings API in favour of the theme customizer? Should we all slowly be moving towards it, or would we be better off sticking to the settings API? Can they live side-by-side, and if so, where would the division of responsibilities lay?

share|improve this question

migrated from meta.wordpress.stackexchange.com May 1 '13 at 9:49

This question came from our discussion, support, and feature requests site for WordPress developers and administrators.

2 Answers 2

up vote 12 down vote accepted

The premise of the question is flawed. The Customizer API is not an options API, but rather an options preview API. The Customizer API relies on either the Settings API or the Theme Mods API to register controls for existing settings added via either of the two APIs.

The Customizer does not - and cannot - define/register new settings that have not already been registered via either the Settings API or the Theme Mods API. Said a different way: The Customizer API is not an API to add settings directly to or to retrieve settings directly from the database; rather, the Customizer API uses either the Settings API or the Theme Mods API to save settings to, or to retrieve settings from, the database.

Thus, the Customizer API isn't an alternative to one of the existing options APIs; rather, it is an alternative for a settings page. The Customizer doesn't care whether a setting is registered via the Settings API or the Theme Mods API, and such settings can be mixed and matched in the Customzer. In fact, in most cases, such settings are mixed and matched: custom header and custom background are Theme Mods, and Site Title and Description are Settings API.

To understand exactly how settings and controls are registered via the Customizer API, I recommend reading Otto's excellent tutorials:

So, the question isn't either/or with respect to the specified APIs. Appropriate either/or questions would be:

  • Use either the Settings API or the Theme Mods API to register existing settings to preview via the Customizer API
  • Use either the Customizer API or a custom Theme settings page to allow the user to configure Theme options.
share|improve this answer
    
Thanks Chip. I still don't 100% follow you, but you've given me enough to go and look into the issue some more. I think my confusion stems from the overlap in functionality and the similarity in the names. Is there page that clearly documents the use cases (in a more abstracted way) of the different APIs? I haven't had much luck looking through the codex; it just focuses on the nuts and bolts of applying the API. –  Dre May 2 '13 at 12:00
    
I've added more, to try to explain a bit more in-depth. See also, especially, the links to Otto's Customizer tutorials; I think they will help clarify things. –  Chip Bennett May 2 '13 at 12:19
    
You sir are a gentleman. –  Dre May 2 '13 at 13:06

As simple as things can sometimes be: The Settings API is not the Theme Customizer. Both are different things for different tasks.

Settings API

You're either writing a plugin or have a theme that doesn't have options that won't need any visual feedback? Go with this option.

Theme Customizer

You need to have options that have a visual impact that the user should be able to see? Go with this option.

share|improve this answer
    
This was my initial conclusion. However, there is a great deal of functional overlap between the two, which is what lead to the original question(s). Additionally, the idea of splitting up theme options into two locations depending on whether they are visual or not strikes me as problematic from a UX point of view. That's not to say that I disagree with you; I'm just soliciting opinions at this stage. The whole topic itself is somewhat murky. Perhaps some well defined guidance 'from on high' would be beneficial. Thanks for your input! –  Dre May 1 '13 at 10:33
    
@Dre Guess you misread it a bit: If you got even one single option that needs visual feedback, go with the ThemeCustomizer. So the rule of thumb is: Theme -> Theme Customizer | Plugin -> Settings API. –  kaiser May 1 '13 at 10:59
    
As a general rule, all Theme-defined options should have a presentational impact. :) That said: the Customization API requires either the Settings API or the Theme Mods API in order to exist. The Customization API isn't an alternative for one of those two APIs, but rather an alternative for a custom Theme settings page. –  Chip Bennett May 1 '13 at 14:26
    
Do you guys have any resposiveness issues with the customizer? It seems quite temperamental for me in both 3.5.1 and even more so in 3.6(trunk). I find the heading and close/save buttons often just don't respond properly to clicks and having to sometimes click them several times(and more so in trunk). This is in both FF and Chrome. –  t31os May 1 '13 at 15:18
    
@t31os Had this problem before, but without consistency. But haven't tried for quite some time. I'd suggest to console.log() all your actions so you see what's triggered and what's interrupting. JavaScript debugging isn't easy... –  kaiser May 1 '13 at 15:48

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.