Theme Frameworks Integration

You can control Views settings using option screens. This is useful when you develop Toolset-based themes and you want to create option screens that determine what displays in different places. In this document, we describe the API, which allows you to declare your option frameworks..

Here are some examples of what you can achieve with option screens for Views:

• A slideshow on the front page was created with Views, and there is a theme option to set how many items it should display.
• A Views widget lists the last 5 posts from one featured category, and the user might be able to change the category that he wants to feature.
• There is a page displaying a custom search form, and an option to determine how many results per page should be shown.

How theme options connect to Views settings

1. Register a theme framework, using one of the two available methods.
2. Select the theme options that you want to expose to different Views in your site.
3. Edit the Views that require control by the theme. You will see the theme options which you selected.

Registering a framework

You need to register the theme framework that you want to use and set values for Views in your site. If you are using custom PHP code to create option screens, you still need to register a dummy framework, so that you can continue and set inputs to Views. This registration is needed so that you can load options from the database and name them.

Note that you can register only one theme framework. You can check whether a framework is correctly registered, using wpv_api_register_framework(). This function returns true on success or false on failure.

There are two ways to register a theme framework. Using the auto-detection feature or registering manually with the integration API.

Auto-detected framework

Views auto-detects the most used frameworks and offers an easy way to register them, in case they are installed. It also provides links to documentation pages, even if the framework is not installed.

In order to register an installed framework, go to the Toolset -> Settings page and click the Views Integration tab. There, select a framework from the list and click Save. If you already a framework from this list registered and select to enable another one, you will get a warning that all the registered keys will be lost.

Currently, four theme frameworks can be auto-detected by Views:

• Options Framework
• OptionTree
• UpThemes
• Customizer (as site options or theme modifications)
• Cherry Framework

Registering Customizer

Views settings provide two different ways to register Customizer automatically. The main difference how options are stored in the database. More specifically:

• site options are stored directly in the wp_options table of your WordPress database and apply to the site regardless of the active theme.
• theme mods are specific to a particular theme, allowing to have a unique set of options when switching themes.

You can learn more about Customizer options and how to register them, in the official theme handbook of WordPress.

Ιntegration API

Use the wpv_api_register_framework() function (available since Views 1.8):

Registering the theme framework

add_action( 'init', 'wpv_dummy_framework_api' );
  
function wpv_dummy_framework_api() {
    $framework_id = 'OptionTree';
    $framework_data = array(
        'name' => __( 'OptionTree' ),
        'api_mode' => 'function',
        'api_handler' => 'ot_get_option',
    );
    if ( function_exists( 'wpv_api_register_framework' ) ) {
        wpv_api_register_framework( $framework_id, $framework_data );
    }
}

Theme frameworks should be registered at init. The wpv_api_register_framework() function has two required arguments:

• framework_id is a string that contains an identifier for the theme options framework. It can be any custom string and should be unique. You should also avoid starting this string with a number (to avoid exporting issues).
• framework_data is an array that contains some important information about how the framework works.

Views will store some related information using this framework_id as a primary key, so sharing this key with other frameworks or themes could produce unexpected results.

framework_data is an array with three main elements:

• name is an optional string containing the display name that will be used to refer to the framework. If it is missing, Views will use the framework_id instead.
• api_mode is a mandatory string that states the way that the framework gets the value for each of its options. Some frameworks have a dedicated function for this (so they should pass a function here as the value). Some other frameworks just store their data in a serialized array in the WordPress options, so they should pass an option here as the value.
• api_handler is a mandatory string that complements the api_mode one. It should contain the relevant data on the selected mode. In case the framework has a dedicated function to get option values, api_handler should be that function’s name. If the framework just accesses a serialized array stored as a WordPress option, the key of that option should be passed here.

We do not support frameworks storing their settings in other ways, but we are open to extending this to meet everyone’s needs.

Declaring options

After registering a theme framework, a new section will appear, called Registered Framework, just under the Autodetected Frameworks section.

You can use this section to declare which options will be available as values for the relevant Views settings.

For example, there might be an option frontpage_slider_limit that sets how many slides should appear on the slideshow on the homepage, as an integer. After declaring this option here, that value will be available as an option in Views for the setting controlling the number of items to be returned.

Declared options will be stored by Views, linked to the framework_id, and offered as options in key settings for Views queries. They will also be exported and imported with Views.

Applying options

After declaring theme framework options within Views, they will be available when creating or editing a View:

By now, declared theme framework options will be available on the following View settings:

• Limit and offset, for all Views no matter if they list posts, taxonomies or users.
• Pagination Posts per page, both for manual and automatic pagination.
• Almost all Query Filters.

You can also print the value of a stored option on the front-end, using the wpv-theme-option shortcode (available since Views 1.10). This shortcode takes a name as an argument and returns the value of this option for the registered framework:

[wpv-theme-option name="key"]

Expected data

Each View setting expects a different kind of data. This means that the theme framework could assign a theme option for a View setting that provides some data that might not be compatible with the setting itself. For example, the limit setting of a View expects an integer but could be passed a string or an array as the value.

Views implements specific checks to all returned values from the theme framework, in order to ensure that those cases do not produce any errors. In case the returned value does not fit the expected type:

• For limit and offset settings, default to no limit and no offset.
• For pagination, defaults to 10 items per page.
• For Query Filters, default to applying no filter.

The following is a detailed list of the expected data on each of the View settings that can be filled with option framework values: