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.

Views auto-detects most used theme frameworks
Views auto-detects most used theme frameworks

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.

Options for registered theme frameworks in Toolset Settings, under Views Integrations tab
Options for registered theme frameworks in Toolset Settings, under Views Integrations tab

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:

Apply options into a View
Apply options into 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:

View settingExpected type of value
Limit, offset and pagination (posts per page)Expects a numeric value.
Query Filter by Post AuthorThis Query Filter has two modes: filter by author IDs or by author usernames. IDs expects an array of numbers or a comma-separated list of numbers (user IDs), and will take out any non-numeric value. usernames expects an array of usernames or a comma-separated list of usernames, and will take out any possible value not matching an existing username.
Query Filter by Post IDThis Query Filter expects an array of numbers or a comma-separated list of numbers (post IDs), and will take out any non-numeric value.
Query Filters by Post Parent or by Post RelationshipExpect an array of numbers or a comma-separated list of numbers (post IDs) and will take out any non-numeric value.
Query Filter by TaxonomyExpects an array of numbers or a comma-separated list of numbers (term IDs), and will take out any non-numeric value. Please note that Views will filter by term_id values.
Query Filter by Custom FieldsExpects a mixed range of types. Views does the conversion to the one needed in each moment.
Query Filter by specific Taxonomy TermsExpects an array of numbers or a comma-separated list of numbers (term IDs), and will take out any non-numeric value. Please note that Views will filter by term_id values.
Query Filter by Usermeta FieldsExpects a mixed range of types. Views does the conversion to the one needed in each moment.