There seems to be a great deal of confusion regarding the various APIs involved with Theme options, especially regarding the interactions among those APIs. This confusion is obvious in discussions involving the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings.. This post will attempt to explain the various APIs and how they work together.

The first thing to understand is the various interactions with options: storing options in the database, retrieving options from the database, and user configuration of options.

Storing and Retrieving Options

WordPress has two APIs for storing and retrieving Theme options: the Options API and the Theme Modification (Theme Mods) API. The Options APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is the “granddaddy” API, used by coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and Plugins, as well as Themes. The Theme Mods API is a Theme-specific API.

The Options API uses the add_option() and update_option() functions to store options to the database, and get_option() to retrieve options from the database. The Theme Mods API uses the set_theme_mod() to store options to the database, and get_theme_mod() and get_theme_mods() to retrieve options from the database. Neither API deals with user configuration (e.g. Settings pages) of options.

User Configuration of Options

There are essentially three ways to allow users to configure Theme options: a Settings API-generated settings page, a custom settings page, and the Customizer API. Both a settings page and the Customizer display options retrieved by either the Settings API or the Theme Mods API, then return user-configured settings to that same API for storage in the database.

(Note: where the Theme Review Guidelines formerly recommended using the Settings API, that recommendation applied to using the Settings API to generate the settings page, rather than the Theme creating a custom settings page. That recommendation has been superseded by the recommendation to use the Customizer.)

The Settings API includes a robust set of functions to generate a Settings page, but is missing some key elements such as default markup for settings fields, and standard sanitization/validation based on option data type. This void is frequently filled by the various option framework libraries available. Using such frameworks avoids the necessity of the Theme developer to roll their own code. These frameworks generally also handle the sometimes complex callback structure needed to implement the Settings API fully. (And no joke; fully implementing the Settings API is so complex that I wrote a ten-page tutorial on it a few years ago.)

Until the Customizer, the only other option was a completely custom Theme settings page. These used to be all the rage (and can still be found in many options frameworks), and were promoted as a Theme “feature”. All they really did was add a non-core UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. and increase the learning curve for Theme developers and users alike. That’s why the Theme Review Guidelines used to recommend use of the Settings API to generate Theme settings pages.

Now, for Themes that opted to use the Theme Mods API, a custom Theme settings page was the only option. The Theme Mods API is, overall, probably a better and easier API to understand and to use – but it did not include an API for creating a settings page.

Customizer API

Now, a third option exists: the Customizer.

It is important to keep in mind here that the Customizer is not an API for storing or retrieving settings; it is an API for user configuration of settings. It is not a replacement for either the Settings API or the Theme Mods API for storing/retrieving options; it is a replacement for Theme settings pages. The Customizer does not store options to or retrieve options from the database. It merely displays options retrieved by either the Theme Mods API or the Settings API, and returns settings to either the Theme Mods API or the Settings API for storage in the database.

This is a very important distinction to remember, because, while the Customizer defaults to using the Theme Mods API, it can be used with either the Theme Mods API or the Settings API. This flexibility is important for existing Themes as well as for new Themes. Developers of existing Themes that use the Settings API, and who want to migrate away from settings pages and toward use of the Customizer can do so quite easily. And Developers of new Themes that want to take advantage of the Customizer from the beginning can do so just as easily.

Key Points

1. Theme Mods API and Options API are used to store/retrieve options
2. Settings pages and the Customizer are used to allow users to configure options
3. The Customizer can replace a Settings page and the Settings API, but cannot replace either the Theme Mods API or the Options API
4. The Customizer can be used on top of either the Theme Mods API or the Options API
5. Themes that currently use the Settings API, either directly or using an options framework library, can use the Customizer without changing any of the underlying options code already in use
6. Themes that currently use a Settings page with the Settings API can add Customizer support without impacting or removing the current Settings page
7. New Themes are recommended to use the Customizer with the Theme Mods API

#customizer-api, #options-api, #settings-api, #theme-mods-api