Almost all WordPress themes offer settings to control the appearance of “single” pages and “archives.” However, almost no theme allows controlling these settings for custom post types. Toolset makes this possible by allowing users to select theme settings for templates and archives of custom post types.

Users can, therefore, create sites that have custom post types and can have full control over the theme settings for each custom type.

You need to create a JSON configuration file, namely toolset-config.json to add this support to your theme. The file must then be placed in the root folder of the theme or the child theme. When Toolset is not running, this file does nothing. Toolset will look for this configuration file and identify which settings the theme offers.

What to include in the toolset-config.json file

The configuration file should include all the settings that allow users to control the appearance of content on the front end. Each theme has its own settings; however, some common elements that many themes have are as follows:

  • Sidebar selection (e.g. left/right/no-sidebar)
  • Enable/disable post title
  • Enable/disable featured image
  • Content container (width, margins, etc.)
  • Enable/disable featured image
  • For achives:
    • Enable/disable the archive title
    • Enable/disable pagination

Settings for templates

You want to allow users to control all the “page settings” when they design templates. For example, the post editing screen for the Astra theme is as follows:

If I design a template for “Places,” I want that template to control all the theme settings that are available when editing a single “Place.” In this case, the configuration file will prompt Toolset to offer “sidebar,” “content layout,” “disable title,” “disable small footer,” and “disable primary header” options. Each theme offers different settings per page.

Theme settings that Toolset can control
Theme settings that Toolset can control

Settings for archives

For archives, look for theme settings that will control the appearance of archive pages. These settings will be in the WordPress Customizer, and can be found on the Appearance -> Customize page. Often, they will be in different Customizer sections.

Controlling theme options using Customizer
Controlling theme options using Customizer

For example, in the Astra theme, we want to allow to control the “sidebar layout” and “content layout” settings for archives.

How to create the toolset-config.json file

The JSON file follows a very basic schema for defining settings and their values.

A basic configuration object is represented as follows:

At the root of the configuration object, we have three properties:

1. global_store_type (required) (string):

This holds the method the theme stores its global options in, which could be one of the following three:

  • array —the theme stores its options in a single serialized array.
  • single—the theme stores options as individual WordPress options.
  • customizer—the theme uses the WP Customizer API to store the options.

2. global_store_name (required when global_store_type is an array) (string):

If the global_store_name is an array, this property will hold the name of the WP option that is used to retrieve the array.

3. sections (array):

A section is an array of objects that defines different setting sections. Each section could have multiple options, and it is recommended to group related options together, particularly if certain sections serve specific display purpose, such as individual posts or archive pages.

The root of each section object has four properties:

  1. section_type (optional) (string)—when set, the value can either be “posts” or “archive” and defines where the section should be displayed. “posts” display for Content Layouts or Layouts assigned to single posts, and display for Content Templates if Layouts is not activated. However, if it is set for an archive, the section will display for Layouts assigned to archive pages and for Custom WordPress Archives created by Views.
  2. section_title (required) (string)—a string that will show as the section header.
  3. section_summary (required) (string)—explanation string for the functionality of the section’s options.
  4. options (required) (array)—an array of objects where each object defines an individual option that belongs to the section. The option object has the following properties:
    • name (required) (string)—holds the name of the option. Should be equal to the name the option is saved with in the theme options array or the individual WordPress Option.
    • gui (required) (object)—an object that holds the GUI properties of the option. This object has the following properties:
      • display_name (required) (string)—the display name used in the input label.
      • type (required) (string)—can be text, radio, checkbox, select, or password.
      • values (required for all option types except text and password) (array) —an array of objects, where each object holds two properties: “text” used for value Display, and “value,” which is stored and used when loading values.
      • default_value (required) (mixed)—used when no value is stored.

Allowing Toolset to disable the theme’s pagination

Toolset features its own pagination feature when listing contents, so when the theme has its own pagination, it is displayed twice on the front-end. Naturally, this does not look good.

To fix this, the theme has to implement an option for hiding its pagination. That option can be implemented using one of the three methods that Toolset supports:

  • As an individual WordPress option.
  • As a WordPress single options array.
  • Using the WordPress Customizer API.

Implementation using an individual WordPress option

1. Add a WordPress option named, “theme_disable_pagination”, for example. This is done using the add_option(‘theme_disable_pagination’, 0) function.

2. Add a user interface to control this option in your theme.

3. To interface with Toolset, you need to add this option to your configuration file (click to expand):

 

4. Now you need to use the option you just added. For example,  your theme’s archive.php file contains a theme_pagination() function that outputs the pagination user interface. In this example, you need to wrap this function in an if conditional statement so that the pagination is output only if the related option is set (click to expand):

 

Implementation using a single options array

1. First, add an item named, for example, “theme_disable_pagination” to your WordPress options array. For this you can use the following function:

  • add_option(‘theme_settings’, array(“theme_disable_pagination” => 0), … rest of your options)

2. Add the user interface to control this options in your theme.

3. To interface with Toolset Integration you need to add this option to your configuration file (click to expand):

4. Now you need to use the option you just added. For example,  your theme’s archive.php file contains a theme_pagination() function that outputs the pagination user interface. In this example, you need to wrap this function in an if conditional statement so that the pagination is output only if the related option is set (click to expand):

Implementation using Customizer API

1. First, add an item named, for example, “theme_disable_pagination” to your Customizer options using the following function:

  • $wp_customize->add_setting( ‘theme_disable_pagination’ , array(‘default’   => 0 ) );

2. To interface with Toolset Integration, you need to add this option to your configuration file (click to expand):

3. Now you need to use the option you just added. For example,  your theme’s archive.php file contains a theme_pagination() function that outputs the pagination user interface. In this example, you need to wrap this function in an if conditional statement so that the pagination is output only if the related option is set (click to expand):

How to test the configuration file

Place the newly created config file in the theme’s root folder. Install the following Toolset plugins:

  • Toolset Types
  • Toolset Views

 

Go to the Toolset –> Dashboard page and create a new custom post type. Then, from Toolset –> Dashboard, create a new “template” and “archive” for the new  post type .

Creating a template or archive using the Toolset Dashboard page
Creating a template or archive using the Toolset Dashboard page

You should see the settings that you selected when designing the template (Content Template) and archive (WordPress Archive).

Theme options shown in the Toolset editor
Theme options shown in the Toolset editor

When a setting is changed, it is automatically applied to all the posts that use the template.

Similarly, when you design an archive, the settings added to the JSON file, and set for the archive, will be applied. These changes appear on the front-end, when you view the archive page.