Extending the WordPress Customizer using Kirki
WordPress Themes can now be customized through the native WordPress Customizer only. Effective immediately, theme authors can include customization options for their theme using only the Customizer.
The WordPress Theme Review team decided to enforce all the theme authors to provide customization options for their themes using the native WordPress Customizer only. As it sums up, using of frameworks like Option Tree, Redux will not be so helpful at present since they make use of separate pages for their options and their options are inaccessible through the WordPress Customizer, although Redux is working on rebuilding its options to be used through the Customizer.
Sarah Gooding wrote a nice article about this on WPTAVERN.
Both Redux and Kirki have joined forces together to provide better support for the WordPress Customizer. Redux is working on making its framework to work fully in the Customizer.
WordPress Customizer
The WordPress Customizer was added in WordPress 3.4 and it allows developers to customizer the design of the website using the Customizer option. The Theme Customization screen (i.e. “Theme Customizer”) allows site admins to tweak a theme’s settings, color scheme or widgets, and see a preview of those changes in real time. More information about the WordPress Customizer can be gathered from the WordPress Theme Customization API and from the Theme Options — The Customizer API.
Built-in options
However, it’s a great idea to use the Customizer only since it can provide live changes to any WordPress website. Customizer has the follwoing sections built-in:
- title_tagline — Site Title & Tagline
- colors — Colors
- header_image — Header Image
- background_image — Background Image
- nav — Navigation
- static_front_page — Static Front Page
Along with these, menu customizer will also be included in the next version of WordPress. More information about the WordPress Customizer can be obtained from the WordPress Theme Handbook.
Options provided in the Customizer core
The Customizer API is object-oriented. There are four main types of Customizer objects: Panels, Sections, Settings, and Controls. Settings associate UI elements (controls) with settings that are saved in the database. Sections are UI containers for controls, to improve their organization. Panels are containers for sections, allowing multiple sections to be grouped together.
The Customizer core provides several built-in control types:
- checkbox
- textarea
- radio (pass a keyed array of values => labels to the choices argument)
- select (pass a keyed array of values => labels to the choices argument)
- dropdown-pages
For any input type supported by the html input element, simply pass the type attribute value to the type parameter when adding the control. This allows support for control types such as text, hidden, number, range, url, tel, email, search, time, date, datetime, and week, pending browser support.
Nguyễn Đình Quân has written an excellent article about extending the WordPress Customizer and Paulund has made a collection of custom controls you can use in your Wordpress theme customizer page.
Kirki
According to its wiki page, Kirki is not a framework. It’s a Toolkit allowing WordPress developers to use the Customizer and take advantage of its advanced features and flexibility by abstracting the code and making it easier for everyone to create beautiful and meaningful user experiences.
Kirki is a toolkit allowing WordPress developers to use the Customizer and take advantage of its advanced features and flexibility by abstracting the code and making it easier for everyone to create beautiful and meaningful user experiences.
Options provided in Kirki
Kirki makes it much easier than other frameworks since its implementation is fairly similar to the WordPress Customizer but it offers much more functionality with many built-in options and the option to build much more. Kirki already has the following options built-in:
- Radio-Buttonset
- Radio-Image
- Radio
- Checkbox
- Color
- Color-Alpha
- Dropdown Pages
- Image
- Background
- Multicheck
- Select
- Slider
- Text
- Textarea
- Upload
- Switch
- Toggle
- Sortable
- Number
- Palette
- Editor (WYSIWYG editor)
You can already see that Kirki offers a wide range of options than the native WordPress Customizer. Not only this, you can also create your own custom functions using Kirki.
Implementation
We will be discussing about how to use Kirki in your themes using the Github version of Kirki in order to avoid adding any more plugins. Implementation of options using Kirki is fairly similar to the Customizer and consists of the following steps:
- Linking Kirki with your theme
- Creating a new Configuration
- Adding Panels
- Adding Sections
- Adding Fields
Linking Kirki with your theme
At first, download the files from Github and put them in a separate folder named kirki under your theme’s directory. Suppose, our theme name is Infiword, then we would be keeping this folder under wptheme\wp-content\themes\infiword\ in a folder named kirki.
You will need to link Kirki with your theme. To do this, you can add the following code to your functions.php file:
include_once( get_template_directory() . '/kirki/kirki.php' );Note: You can also create a separate file named theme-options.php and include it from the functions.php file just for keeping the options in a separate file and keeping your functions.php clean. In this tutorial we will be following this method.
To do this, create a folder named library in your wptheme\wp-content\themes\infiword\ folder and then make a file named theme-options.php in wptheme\wp-content\themes\infiword\library. Add the file to your functions.php using the following code:
/* ------------------------------------------------------------------------- *
* This line links the theme-options.php file with the theme
/* ------------------------------------------------------------------------- */require_once('library/theme-options.php');
In this theme-options.php file, we will add the code to link Kirki with our theme. This file now contains the following code only:/* ------------------------------------------------------------------------- *
* This file adds the options that are supported by this theme.
/* ------------------------------------------------------------------------- */include_once( get_template_directory() . '/kirki/kirki.php' );
Upon linking the Kirki files with our theme, we won't see any changes in our Customizer.
Creating a new configuration
At first, we will have to create a configuration for our theme options. Configurations have a unique ID and all fields that use the same config_id will inherit the properties of that configuration.
Once you add your configuration you can then add panels, sections and fields. Please note that you should have at least 1 section in your customizer in order to be able to add fields. Fields can’t be ‘orphan’, they have to be grouped in a section.
The syntax for adding a configuration to our theme is:
/* ------------------------------------------------------------------------- *
* Default syntax for adding configuration in Kirki.
/* ------------------------------------------------------------------------- */Kirki::add_config( $config_id, $args );
Kirki allows you to create configurations for your plugins or themes and group them by an id. All fields that are then linked to that ID will inherit the configuration properties./* ------------------------------------------------------------------------- *
* Default syntax for adding configuration to our theme in details.
/* ------------------------------------------------------------------------- */Kirki::add_config( 'my_theme', array(
'capability' => 'edit_theme_options',
'option_type' => 'option',
'option_name' => 'my_theme',
) );
- capability : any valid WordPress capability.
- option_type : can be either option or theme_mod.
- option_name : If you’re using options instead of theme mods then you can use this to specify an option name. All your fields will then be saved as an array under that option in the WordPress database.
We will be now adding a similar code to our own theme-options.php file to make our theme configuration. Since, the name of our theme is Magnificient_Kirki, we will be naming our configuration mk (abbreviated form for Magnificient_Kirki). You can use any name for this configuration.
Add the following code to your theme-options.php file:
/* ------------------------------------------------------------------------- *
* Adding the configuration to our theme.
/* ------------------------------------------------------------------------- */Kirki::add_config( 'mk', array(
'capability' => 'edit_theme_options',
'option_type' => 'option',
'option_name' => 'mk',
) );Adding panelsPanels wrap up a particular section of our themes together. For example, we want to provide the customization options about the footer of our theme. We can wrap up that section under a panel named Footer. This panel groups together all the option related to the theme's footer.The syntax for adding a panel to our theme is:/* ------------------------------------------------------------------------- *
* Default syntax for adding a panel in Kirki.
/* ------------------------------------------------------------------------- */Kirki::add_panel( $panel_id, $args );
Adding arguments in panels using Kirki is similar to the WordPress Customizer.
- title : The visible name of a panel.
- priority : This controls the order in which this panel appears in the Theme Customizer sidebar.
- description This optional argument can add additional descriptive text to the panel.
/* ------------------------------------------------------------------------- *
* Adding a panel to our theme using Kirki with all the fields.
/* ------------------------------------------------------------------------- */Kirki::add_panel( 'panel_id', array(
'priority' => 10,
'title' => __( 'My Title', 'textdomain' ),
'description' => __( 'My Description', 'textdomain' ),
) );
The Kirki::add_panel() method is nothing more than a wrapper for the WordPress customizer API and therefore follows the exact same syntax.We will be now adding a panel Header to our theme customizer. We need to add the following code to our theme-options.php file/* ------------------------------------------------------------------------- *
* Adding a panel to our theme.
/* ------------------------------------------------------------------------- */Kirki::add_panel( 'header', array(
'priority' => 10,
'title' => __( 'Header', 'theme_slug' ),
'description' => __( 'This panel will provide all the options of the header.', 'theme_slug' ),
) );
Now, even if we refresh the Customizer in our WordPress website, we will see no visual differences since we still haven't added any sections and controls. We will next add sections to our panels.Adding sectionsSections are wrappers for fields, a way to group multiple fields together. Like panels are wrappers for sections, sections are wrappers for fields. All fields must belong to a section, no field can be an orphan.The syntax for adding a section to our theme is:/* ------------------------------------------------------------------------- *
* Default syntax for adding a section.
/* ------------------------------------------------------------------------- */Kirki::add_section( $panel_id, $args );
A more detailed syntax will be as the one below:/* ------------------------------------------------------------------------- *
* Full syntax for adding a section to a panel in our theme using Kirki
/* ------------------------------------------------------------------------- */Kirki::add_section( 'custom_css', array(
'title' => __( 'Custom CSS' ),
'description' => __( 'Add custom CSS here' ),
'panel' => '', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );
We will add a section to our Header panel of our theme customzer. Just add the following code to our theme-options.php file:/* ------------------------------------------------------------------------- *
* Adding a section to our theme.
/* ------------------------------------------------------------------------- */Kirki::add_section( 'header_advertisement', array(
'title' => __( 'Header advertisement' ),
'description' => __( 'Add an image to be shown as header advertisement.' ),
'panel' => 'header', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );
The building up of panels and sections are complete. We can now add our fields.
Adding fields
There are three implementations of fields in Kirki that we can use:
- The default WordPress Customizer API
- An array of arrays
- Static method calls
The default WordPress Customizer syntax is one of the most versatile ways to use the Customizer.
/* ------------------------------------------------------------------------- *
* Adding fields to our Customizer using the default WordPress Customizer syntax.
/* ------------------------------------------------------------------------- */function my_custom_text_settings( $wp_customize ) {// Register the settings
$wp_customize->add_setting( 'my_setting', array(
'default' => 'some-default-value',
'type' => 'theme_mod',
'capability' => 'edit_theme_options',
) );$wp_customize->add_setting( 'my_setting_2', array(
'default' => 'some-default-value',
'type' => 'theme_mod',
'capability' => 'edit_theme_options',
) );// Add the controls
$wp_customize->add_control( 'my_setting', array(
'label' => __( 'My custom control', 'translation_domain' ),
'section' => 'my_section',
'settings' => 'my_setting',
'type' => 'text',
'priority' => 10
) );$wp_customize->add_control( 'my_setting_2', array(
'label' => __( 'My custom control 2', 'translation_domain' ),
'section' => 'my_section',
'settings' => 'my_setting_2',
'type' => 'text',
'priority' => 20
) );
}
add_action( 'customize_register', 'my_custom_text_settings' );
For some projects you may find it convenient to write your fields in the form of an array of arrays. This array can then be hooked in the kirki/fields filter and your fields will be automatically added to the customizer. This syntax is simpler than the default Customizer API for most people and still allows you to make a lot of customizations./* ------------------------------------------------------------------------- *
* Adding fields to our Customizer in the form of an array of arrays.
/* ------------------------------------------------------------------------- */function my_custom_text_settings( $fields ) {// Add the controls
$fields[] = array(
'label' => __( 'My custom control', 'translation_domain' ),
'section' => 'my_section',
'settings' => 'my_setting',
'type' => 'text',
'priority' => 10,
'option_type' => 'theme_mod',
'capability' => 'edit_theme_options',
);$fields[] = array(
'label' => __( 'My custom control 2', 'translation_domain' ),
'section' => 'my_section',
'settings' => 'my_setting_2',
'type' => 'text',
'priority' => 20,
'option_type' => 'theme_mod',
'capability' => 'edit_theme_options',
);return $fields;}
add_filter( 'kirki/fields', 'my_custom_text_settings' );
In other projects you may want to add your fields using static method calls. This is the method that we find offers great flexibility and potential without sacrificing the flexibility of the system:/* ------------------------------------------------------------------------- *
* Adding fields to our Customizer using static method calls.
/* ------------------------------------------------------------------------- */Kirki::add_config( 'my_config', array(
'option_type' => 'theme_mod',
'capability' => 'edit_theme_options',
) );Kirki::add_field( 'my_config', array(
'settings' => 'my_setting',
'label' => __( 'My custom control', 'translation_domain' ),
'section' => 'my_section',
'type' => 'text',
'priority' => 10,
'default' => 'some-default-value',
) );Kirki::add_field( 'my_config', array(
'settings' => 'my_setting_2',
'label' => __( 'My custom control 2', 'translation_domain' ),
'section' => 'my_section',
'type' => 'text',
'priority' => 20,
'default' => 'some-default-value',
) );
Please keep in mind that if you do work using the default WordPress customizer API, then you will not be able to take advantage of some of Kirki's more advanced features like automatic CSS output & calculations as well as automatic postMessage script generation. These features will only be available if you use the 2nd or 3rd method of adding your own fields.We will add a static method call to our theme customizer since it offers more flexibility. We need to add the following code to our theme-options.php file:/* ------------------------------------------------------------------------- *
* Adding a field to our theme using Kirki.
/* ------------------------------------------------------------------------- */Kirki::add_field( 'mk', array(
'settings' => 'header_advertisement_setting',
'label' => __( 'Setting for the header advertisement', 'theme_slug' ),
'section' => 'header_advertisement',
'type' => 'image',
'priority' => 10,
'default' => '',
) );
Now, if we refresh our WordPress Customizer, we will see some changes. We will see that the Header panel has been added at the top of all the customizer options.
On clicking the Header panel, the Header advertisement section will be visible. On clicking the Header advertisement section, a dropdown will occur which will have the field for adding the image to be used as the header advertisement.
We have successfully added a section, panel and field. But, even if we upload a picture in the Header advertisement section, no changes will be shown on our website. That’s because we haven’t done any output of the options. We will now provide an output for the options.
Getting the values
To get the value of any of your settings you can use either the WordPress core functions get_option and get_theme_mod, or the kirki-specific Kirki::get_option() method.
The syntax for getting the values is:
/* ------------------------------------------------------------------------- *
* Getting values in Kirki.
/* ------------------------------------------------------------------------- */$value = Kirki::get_option( $config_id, $option_id );
Benefits of using the Kirki::get_option() method:
- It works no matter if you’re using theme_mods, serialized options or individual options.
- You don’t have to define a default value as it’s automatically retrieved from the API.
- Simple and consistent
We will be showing the header advertisement on our header.php file. We need to find a suitable place for our advertisement to show. We can show the advertisement beside our logo. We just need to add the following code there:
/* ------------------------------------------------------------------------- *
* This template will contain the code for the header advertisement.
/* ------------------------------------------------------------------------- */get_template_part( 'templates/advertisement', 'container' );
We will now need to create a templates folder inside our theme main folder.
Inside the templates folder, we need to add a file named header-advertisement.php in which we will be putting all our codes for the header advertisement.
Inside our header-advertisement.php file, we will need to fetch the setting header_advertisement_setting. We will store the value of the setting header_advertisement_setting inside a variable header_advertisement_image and then we can fetch the image src using $header_advertisement_image_src=’<img src=”’.esc_url( $header_advertisement_image ).’”>’;. We will echo the output.
$header_advertisement_image = Kirki::get_option( ‘mk’, ‘header_advertisement_setting’ );
$header_advertisement_image_src=’’;
echo $header_advertisement_image_src;
Now, on refreshing the WordPress Customizer and adding an image to the Header advertisement section, we can see our image.
We have successfully uploaded an image using Kirki. But this was just a stepping stone. We will now explore the possibilities of adding lots of options using this amazing toolkit.
Adding more panels, sections and fields
We just made a successfull integraton of Kirki with the WordPress Customizer. We will now be adding more panels, sections and fields to provide more options. In this tutorial, we will be adding the following options:
- Adding a logo
- Creating layouts for pages
- Creating custom pages for a single category
- Adding Custom CSS
- Adding a footer copyright text
- Customizing font styles for various sections
- Adding image sliders
- Customizing the background colors of various sections
- Adding custom content
If you had understood the first implementation of Kirki, the implementations which we are about to do, will be very easy. Before doing anymore coding, please note that we will be adding panels, sections and fields only inside the theme-options.php file and the output will be done at the various sections of the website as necessary. So, let’s get started!
Adding a logo
In our first point, we will be adding a logo to our website. For adding a logo, we have the Header panel and inside this panel, we will add the Logo section from where we can upload an image. This image will be the image for the logo.
We need to create a section for the logo. Let’s name this section as Logo. This section will be visible inside the Header panel. Open up your theme-options.php file and add the following code:
/* adding header_logo section*/
Kirki::add_section( 'header_logo', array(
'title' => __( 'Logo' ),
'description' => __( 'Add a logo.' ),
'panel' => 'header', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );We will now add an image field from where we can upload the image. For doing so, add the following code to your theme-options.php file:/* adding header_logo_setting field */
Kirki::add_field( 'mk', array(
'settings' => 'header_logo_setting',
'label' => __( 'Setting for the logo', 'theme_slug' ),
'section' => 'header_logo',
'type' => 'image',
'priority' => 10,
'default' => '',
) );
We will now see that the Logo section is finally visible inside the Header panel.
We will now need to provide the output for the logo image. The logo will be shown in the header.php file. Find an appropriate place for the logo and put the following code there:
<?php
$logo_image = Kirki::get_option( 'mk', 'header_logo_setting' );
if ( $logo_image ) : ?>
<a class="navmenu-brand" href='<?php echo esc_url( home_url( '/' ) ); ?>' title='<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>' rel='home'>
<img src='<?php echo esc_url( $logo_image ); ?>' alt='<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>'>
</a>
<?php else : ?>
<h1 class='site-title'><a href='<?php echo esc_url( home_url( '/' ) ); ?>' title='<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>' rel='home'><?php bloginfo( 'name' ); ?></a></h1>
<?php endif; ?>And we will have to logo to be visible once it’s uploaded.
Creating layouts for pages
We will now try to create layouts (left-sidebar, right-sidebar, left-dual-sidebar, right-dual-sidebar, dual-sidebar and full-width) for our front page. This option is very popular and using Kirki, it’s very simple to implement with the radio-image type.
The images are located inside /kirki/assets/images/ folder. You can use your own images also. Open up your theme-options.php file. We will need to create a new panel named Layout from where we can add a section to control the layout of our front page. Just create a new panel using the following code:
/* adding layout panel */
Kirki::add_panel( 'layout', array(
'priority' => 10,
'title' => __( 'Layout', 'theme_slug' ),
'description' => __( 'This panel will provide all the options of the layout.', 'theme_slug' ),
) );Add a section named Front page to our Layout panel using the following code:/* adding layout_front_page section*/
Kirki::add_section( 'layout_front_page', array(
'title' => __( 'Front page' ),
'description' => __( 'Front page layout.' ),
'panel' => 'layout', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );Now, we just need to add the field to control our layout. As said previously, we will use the radio-image type for our field./* adding layout_front_page_setting field */
Kirki::add_field( 'mk', array(
'type' => 'radio-image',
'settings' => 'layout_front_page_setting',
'label' => __( 'Layout for the front page.', 'kirki' ),
'section' => 'layout_front_page',
'default' => 'right-sidebar',
'priority' => 10,
'choices' => array(
'right-sidebar' => get_template_directory_uri() . '/kirki/assets/images/2cr.png',
'left-sidebar' => get_template_directory_uri() . '/kirki/assets/images/2cl.png',
'full-width' => get_template_directory_uri() . '/kirki/assets/images/1c.png',
'dual-sidebar' => get_template_directory_uri() . '/kirki/assets/images/3cm.png',
'left-dual-sidebar' => get_template_directory_uri() . '/kirki/assets/images/3cl.png',
'right-dual-sidebar' => get_template_directory_uri() . '/kirki/assets/images/3cr.png',
),
) );
Refresh your customizer and we will have the Layout panel.
We will now need to create a few templates for our pages. We are offering six options to choose from:
- Right Sidebar
- Left Sidebar
- Right-dual Sidebar
- Left-dual Sidebar
- Full Width (No Sidebar)
- Dual Sidebar
We will be creating a new folder named layouts and inside it, we would create another folder named index-page which will contain all the layouts for the front page.
We will have to edit our index.php file. We will obtain the output using the Kirki::get_option( ‘mk’, ‘layout_front_page_setting’ ) setting and check for each layout (left-sidebar, right-sidebar, left-dual-sidebar, right-dual-sidebar, dual-sidebar and full-width). We will then call the specific layout page using get_template_part() function. Just delete everything inside your index.php file and copy the following code:
<!-- right-sidebar layout -->
<?php if ( Kirki::get_option( 'mk', 'layout_front_page_setting ) == 'right-sidebar' ) { ?><?php get_template_part( 'layouts/index-page/right', 'sidebar' ); ?>
<aside id="sidebar" class="small-12 large-4 columns">
<?php get_sidebar(); ?>
</aside><!-- /#sidebar --><?php } ?>
<!-- /right-sidebar layout -->
This is only for the right-sidebar layout which is also the default layout. We will provide the options for other layouts and then check in the customizer. Add the other layouts using the code below:<!-- left-sidebar layout -->
<?php if ( Kirki::get_option( 'mk', 'layout_front_page_setting' ) == 'left-sidebar' ) { ?>
<aside id="left-sidebar" class="small-12 large-4 columns">
<?php get_sidebar(); ?>
</aside><!-- /#sidebar -->
<?php get_template_part( 'layouts/index-page/left', 'sidebar' ); ?>
<?php } ?>
<!-- /left-sidebar layout --><!-- dual-sidebar layout -->
<?php if ( Kirki::get_option( 'mk', 'layout_front_page_setting' ) == 'dual-sidebar' ) { ?>
<aside id="left-sidebar" class="small-12 large-3 columns">
<?php get_sidebar(); ?>
</aside><!-- /#sidebar -->
<?php get_template_part( 'layouts/index-page/dual', 'sidebar' ); ?>
<aside id="sidebar" class="small-12 large-3 columns">
<?php get_sidebar( 'second' ); ?>
</aside><!-- /#sidebar -->
<?php } ?>
<!-- /dual-sidebar layout --><!-- left-dual-sidebar layout -->
<?php if ( Kirki::get_option( 'mk', 'layout_front_page_setting' ) == 'left-dual-sidebar' ) { ?>
<aside id="sidebar" class="small-12 large-3 columns">
<?php get_sidebar(); ?>
</aside><!-- /#sidebar -->
<aside id="left-dual-sidebar" class="small-12 large-3 columns">
<?php get_sidebar( 'second' ); ?>
</aside><!-- /#sidebar -->
<?php get_template_part( 'layouts/index-page/left', 'dual-sidebar' ); ?>
<?php } ?>
<!-- /left-dual-sidebar layout --><!-- right-dual-sidebar layout -->
<?php if ( Kirki::get_option( 'mk', 'layout_front_page_setting' ) == 'right-dual-sidebar' ) { ?><?php get_template_part( 'layouts/index-page/right', 'dual-sidebar' ); ?>
<aside id="sidebar" class="small-12 large-3 columns">
<?php get_sidebar(); ?>
</aside><!-- /#sidebar -->
<aside id="sidebar" class="small-12 large-3 columns">
<?php get_sidebar( 'second' ); ?>
</aside><!-- /#sidebar --><?php } ?>
<!-- /right-dual-sidebar layout --><!-- full-width layout -->
<?php if ( Kirki::get_option( 'mk', 'layout_front_page_setting' ) == 'full-width' ) { ?><?php get_template_part( 'layouts/index-page/full', 'width' ); ?><?php } ?>
<!-- /full-width layout -->
And at last, add a default layout in case no option is selected.<!-- default layout -->
<?php if ( Kirki::get_option( 'mk', 'layout_front_page_setting' ) == '' ) { ?><?php get_template_part( 'layouts/index-page/right', 'sidebar' ); ?>
<aside id="sidebar" class="small-12 large-4 columns">
<?php get_sidebar(); ?>
</aside><!-- /#sidebar --><?php } ?>
<!-- /default layout -->
We are now ready to check the layouts using our customizer. Refresh the page and check the changes for each layout.
Please note here that each layout will be the choice of the designer and so, the codes of the layouts are not provided here.
Creating custom pages for a single category
We will now create custom pages in which posts from only a single category will be shown. We can control which post we want show using the category_slug of any category. Let’s see how.
We will create a Portfolio page in which posts from the portfolio category will be shown only. At first, we create a file named portfolio-page.php inside our theme folder.
Let’s first create a panel named Portfolio page. Open up your theme-options.php file and just write the following code inside it:
/* adding portfolio_page panel */
Kirki::add_panel( 'portfolio_page', array(
'priority' => 10,
'title' => __( 'Portfolio page', 'theme_slug' ),
'description' => __( 'This panel will provide all the options of the portfolio page.', 'theme_slug' ),
) );Next, we create a section for providing the fields to control the options. Copy the following code inside the theme-options.php file:/* adding portfolio_page_category_slug section*/
Kirki::add_section( 'portfolio_page_category_slug', array(
'title' => __( 'Portfolio page category slug' ),
'description' => __( 'Slug of the category to be shown on the portfolio page.' ),
'panel' => 'portfolio_page', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );And now, we can provide the fields for obtaining the category_slug of the category which is to be shown on the particular page. Just copy the following code inside your theme-options.php file:/* adding portfolio_page_category_slug_setting field */
Kirki::add_field( 'mk', array(
'type' => 'text',
'settings' => 'portfolio_page_category_slug_setting',
'label' => __( 'Category slug', 'kirki' ),
'section' => 'portfolio_page_category_slug',
'default' => '',
'priority' => 10,
) );
Now, refresh you customizer and you will see the Portfolio page panel.
Now, we will edit our portfolio-page.php file to show posts only from a certain category (portfolio category). Open up portfolio-page.php and add the following code:
<?php
/**
Template Name: Custom Portfolio
**/
?><?php get_header(); ?><!-- Row for main content area -->
<div class="small-12 large-12 columns" id="page-content" role="main">
<article <?php post_class() ?> id="post-<?php the_ID(); ?>">
<header>
<h1 class="entry-title"><?php the_title(); ?></h1>
</header>
</article>
<?php /* Start loop */ ?>
<?php if ( Kirki::get_option( 'mk', 'portfolio_page_category_slug_setting' ) ) { ?>
<?php
$portfolio_page_category_slug_setting = Kirki::get_option( 'mk', 'portfolio_page_category_slug_setting' );
?>
<?php query_posts( array ( 'category_name' => $portfolio_page_category_slug_setting, 'posts_per_page' => -1 ) ); ?>
<div class="portfolio-page">
<div id="portfolio-container"><?php while (have_posts()) : the_post(); ?><div class="small-12 large-4 columns" id="portfolio-content" role="main">
<a href="<?php the_permalink(); ?>">
<div class="portfolio-item-link-container">
<div class="portfolio-item-screenshot">
<?php the_post_thumbnail(); ?>
</div>
<div class="portfolio-item-details-tab">
<div id="portfolio-item-name">
<h4><?php the_title(); ?></h4>
</div>
<div id="portfolio-item-meta">
</div>
</div>
</div>
</a>
</div><?php endwhile; // End the loop ?></div>
</div>
<?php wp_reset_query(); ?>
<?php } else { ?>
<?php get_template_part( 'content', 'none' ); ?>
<?php } ?>
</div>
<?php get_footer(); ?>
All we now need to do is to create a page through the WordPress admin.
Now, give the page a heading and select Custom Portfolio from the dropdown inside the Template option under Page Attributes menu.
Now you will need to add some posts with a category (like portfolio) and then add the category_slug to our category slug option in the customizer.
Category slug of each category can be obtained from the categories page inside the admin panel.
If we visit our Portfolio page that we just created, we will see the posts from the portfolio category.
Adding Custom CSS
Many themes provide this option of adding custom CSS to your WordPress website. This option is very much useful if you are not willing to use any plugins. We can use the textarea type to let the user insert the CSS and then the live preview will be shown in the customizer.
For this reason, we create a separate panel named Style inside our customizer using the following code:
/* adding style panel */
Kirki::add_panel( 'style', array(
'priority' => 10,
'title' => __( 'Style', 'theme_slug' ),
'description' => __( 'This panel will provide all the options of the Custom CSS.', 'theme_slug' ),
) );Now, we will be adding the Custom CSS section inside the Style panel using the code below:/* adding style_custom_css section*/
Kirki::add_section( 'style_custom_css', array(
'title' => __( 'Custom CSS' ),
'description' => __( 'Enter your Custom CSS.' ),
'panel' => 'style', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );At the end, we need to add the textarea to get the input from the admin. For doing so, we need to create a Custom CSS field./* adding style_custom_css_setting field */
Kirki::add_field( 'mk', array(
'type' => 'textarea',
'settings' => 'style_custom_css_setting',
'label' => __( 'Custom CSS', 'kirki' ),
'section' => 'style_custom_css',
'default' => '',
'priority' => 10,
) );
And now, we will see the Style panel inside our customizer on refreshing the page.
We will now need to modify our header.php file because that’s where the output of the CSS will be provided. Open up your header.php file and add the following code after:
<?php if( Kirki::get_option( 'mk', 'style_custom_css_setting' ) ) { ?>
<style>
<?php
$custom_css = Kirki::get_option( 'mk', 'style_custom_css_setting' );
echo $custom_css;
?>
</style>
<?php } ?>Now, if we go to the WordPress customizer, refresh the page and insert our Custom CSS inside the textarea, we will see live change.
As you can see that the color of the heading changed with the addition of CSS inside the textarea. Please note here that giving users the ability to add Custom CSS may lead to hacks. So, you must sanitize the output or use Jetpack to allow Custom CSS. This was only for providing options with Kirki. Moreover, if you are the only admin then you can use this option.
Adding a footer copyright text
We can also provide the option to add a custom copyright text. We can use the text option to get the copyright text from the admin and then show that text in the footer. We will create a new panel named Footer.
/* adding footer panel */
Kirki::add_panel( 'footer', array(
'priority' => 10,
'title' => __( 'Footer', 'theme_slug' ),
'description' => __( 'This panel will provide all the options of the footer.', 'theme_slug' ),
) );We will now create a section named Copyright inside the Footer panel./* adding footer_copyright section*/
Kirki::add_section( 'footer_copyright', array(
'title' => __( 'Copyright' ),
'description' => __( 'Enter your copyright text.' ),
'panel' => 'footer', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );And at last, we will be creating the field for storing the text and then echo the output in the footer./* adding footer_copyright_setting field */
Kirki::add_field( 'mk', array(
'type' => 'text',
'settings' => 'footer_copyright_setting',
'label' => __( 'Copyright text', 'kirki' ),
'section' => 'footer_copyright',
'default' => 'WordPress',
'priority' => 10,
) );
Now, we will need to echo this output inside our footer.php file. So, open up your footer.php file and find an appropriate position where you want to echo the copyright text. Then, place the following code there:
if ( Kirki::get_option( 'mk', 'footer_copyright_setting' ) ) {
$footer_copyright_text = Kirki::get_option( 'mk', 'footer_copyright_setting' );
echo $footer_copyright_text;
}
else {
echo "Powered by WordPress";
}If you refresh your customizer now, you will find the copyright text. Change the text and the live changes will be visible now.
Customizing font styles for various sections
In this section, we will be customizing the font style and font family for the various sections of our website. We can use Google fonts since it is integrated with Kirki.
We will make use of the Style panel for providing options about customiziing font style and font family. First, let’s create another section inside the Style panel named Fonts.
/* adding style_fonts section*/
Kirki::add_section( 'style_fonts', array(
'title' => __( 'Fonts' ),
'description' => __( 'Customize your font for the post header..' ),
'panel' => 'style', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );Now, lets provide the field to control the output. We will use the type select. Open up your theme-options.php file and enter the following code:/* adding style_fonts_setting */
Kirki::add_field( 'mk', array(
'type' => 'select',
'settings' => 'style_fonts_family_setting',
'label' => __( 'Font Family', 'kirki' ),
'section' => 'style_fonts',
'default' => 'Roboto',
'priority' => 20,
'choices' => Kirki_Fonts::get_font_choices(),
'output' => array(
'element' => '.post-entry-meta h2 a',
'property' => 'font-family',
'units' => ' !important'
),
) );Kirki::add_field( 'mk', array(
'type' => 'multicheck',
'settings' => 'style_fonts_subsets_setting',
'label' => __( 'Google-Font subsets', 'kirki' ),
'description' => __( 'The subsets used from Google\'s API.', 'example' ),
'section' => 'style_fonts',
'default' => 'all',
'priority' => 22,
'choices' => Kirki_Fonts::get_google_font_subsets(),
'output' => array(
'element' => '.post-entry-meta h2 a',
'property' => 'font-subset',
'units' => ' !important'
),
) );Kirki::add_field( 'mk', array(
'type' => 'slider',
'settings' => 'style_fonts_weight_setting',
'label' => __( 'Font Weight', 'kirki' ),
'section' => 'style_fonts',
'default' => 300,
'priority' => 24,
'choices' => array(
'min' => 100,
'max' => 900,
'step' => 100,
),
'output' => array(
'element' => '.post-entry-meta h2 a',
'property' => 'font-weight',
'units' => ' !important'
),
) );Kirki::add_field( 'mk', array(
'type' => 'slider',
'settings' => 'style_fonts_size_setting',
'label' => __( 'Font Size', 'kirki' ),
'section' => 'style_fonts',
'default' => 30,
'priority' => 25,
'choices' => array(
'min' => 7,
'max' => 48,
'step' => 1,
),
'output' => array(
'element' => '.post-entry-meta h2 a',
'property' => 'font-size',
'units' => 'px !important',
),
) );
I have used .post-entry-meta h2 a because it’s the div that I’ll be customizing. It’s the header for each post. On going to the customizer again, we can fiddle with the Font Family.
You can change the font style of any content. You can also change the Font-size and Font-weight also.
Adding image sliders
Using Kirki, adding image sliders are really easy. We can provide the option to upload images by using the type image and then use any of the available sliders like Flex Slider to achieve this. We will be creating an image slider on our index page above all the post excerpts. We will modify our index page later. First, let’s create the option inside our theme-options.php file.
At first, we use the Layout panel and the Front page section. Inside this section, we add a field named First image of the slider. In this field, we let the admin to upload the first image of the slider.
/* adding layout_front_page_slider_image_one_setting field */
Kirki::add_field( 'mk', array(
'settings' => 'layout_front_page_slider_image_one_setting',
'label' => __( 'First image of the slider', 'theme_slug' ),
'section' => 'layout_front_page',
'type' => 'image',
'priority' => 10,
'default' => '',
) );Now, if we refresh the customizer, we will find the First image of the slider field inside the Front page section.
We will now add two more similar fields to upload two more images for the slider and name them Second image of the slider and Third image of the slider respectively.
/* adding layout_front_page_slider_image_two_setting field */
Kirki::add_field( 'mk', array(
'settings' => 'layout_front_page_slider_image_two_setting',
'label' => __( 'Second image of the slider', 'theme_slug' ),
'section' => 'layout_front_page',
'type' => 'image',
'priority' => 10,
'default' => '',
) );/* adding layout_front_page_slider_image_three_setting field */
Kirki::add_field( 'mk', array(
'settings' => 'layout_front_page_slider_image_three_setting',
'label' => __( 'Third image of the slider', 'theme_slug' ),
'section' => 'layout_front_page',
'type' => 'image',
'priority' => 10,
'default' => '',
) );
We will now need to add the Flex Slider css and js with our theme. Follow the steps:
- Download the Flex slider css and js from their website
- On unzipping, you will find a lot of files. Just copy the flexslider.css and jquery.flexslider.js files and copy them inside your theme folder
- Enqueue the files by adding the following code inside your functions.php file:
// adding flexslider scripts file in the footer
wp_register_script( 'flexslider-js', get_template_directory_uri() . '/jquery.flexslider.js', array( 'jquery' ), '', true );
wp_enqueue_script( 'flexslider-js' );if( ! function_exists( 'theme_slug_enqueue_style' ) ) {
function theme_slug_enqueue_style(){
// flexslider stylesheet
wp_register_style( 'theme_slug-flexslider-stylesheet', get_stylesheet_directory_uri() . '/flexslider.css', array(), '' );
wp_enqueue_style( 'theme_slug-flexslider-stylesheet' );
}
}
add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_style' );Now, we will have to modify our index.php file. Find a suitable place to write the following code for the slider:<?php if ( Kirki::get_option( 'mk', 'layout_front_page_slider_image_one_setting' ) || Kirki::get_option( 'mk', 'layout_front_page_slider_image_two_setting' ) || Kirki::get_option( 'mk', 'layout_front_page_slider_image_three_setting' ) ) { ?>
<!-- slider -->
<div class="small-12 large-12 columns flexslider" id="slider">
<ul class="slides">
<?php
if ( Kirki::get_option( 'mk', 'layout_front_page_slider_image_one_setting' ) ) { $slider_image_one = Kirki::get_option( 'mk', 'layout_front_page_slider_image_one_setting' ); }
if ( Kirki::get_option( 'mk', 'layout_front_page_slider_image_two_setting' ) ) { $slider_image_two = Kirki::get_option( 'mk', 'layout_front_page_slider_image_two_setting' ); }
if ( Kirki::get_option( 'mk', 'layout_front_page_slider_image_three_setting' ) ) { $slider_image_three = Kirki::get_option( 'mk', 'layout_front_page_slider_image_three_setting' ); }
?>
<?php if ( $slider_image_one ) { ?> <li><img src="<?php echo $slider_image_one; ?>" class="my-custom-class" /></li> <?php } ?>
<?php if ( $slider_image_two ) { ?> <li><img src="<?php echo $slider_image_two; ?>" class="my-custom-class" /></li> <?php } ?>
<?php if ( $slider_image_three ) { ?> <li><img src="<?php echo $slider_image_three; ?>" class="my-custom-class" /></li> <?php } ?>
</ul>
</div>
<!-- slider --><script type="text/javascript">
(function($) {
$(window).load(function() {
$('.flexslider').flexslider({
animation: "slide",
prevText: " ",
nextText: " ",
slideshow: true,
directionNav: true,
pauseOnHover: true,
slideshowSpeed: 7000,
animationSpeed: 600,
smoothHeight: true,
});
});
})(jQuery);
</script><?php } ?>
Now, on refreshing our customizer and adding images, we will see a slider.
Customizing the background colors of various sections
We can also customize the backgrounds of various sections of our website using Kirki by using the type color. We will customize the background of our header.
We can make use of the Header panel and create a new section named Background color.
/* adding header_background_color section*/
Kirki::add_section( 'header_background_color', array(
'title' => __( 'Background color' ),
'description' => __( 'Change the background color of the header.' ),
'panel' => 'header', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );Now, we can provide the field to add the type color./* adding header_background_color_setting field */
Kirki::add_field( 'mk', array(
'type' => 'color',
'settings' => 'header_background_color_setting',
'label' => __( 'Background color of the header', 'kirki' ),
'section' => 'header_background_color',
'default' => '#0088cc',
'priority' => 10,
'output' => array(
'element' => 'body > header.contain-to-grid',
'property' => 'background-color',
'units' => ' !important'
),
) );
On refreshing the customizer, we will find that the header of our website has changed to our default color (#0088cc). We can then change the color as we like.
Please note here that we could have also used the type background which would also let us the ability to upload images. Since, we don’t need that functionality, we used the type color.
Adding custom content
We can also add custom content using the type custom. Adding the type custom is simple. We will add the custom to our Footer panel inside a Custom sections using the code below:
/* adding footer_custom section*/
Kirki::add_section( 'footer_custom', array(
'title' => __( 'Custom' ),
'description' => __( 'Customize your footer.' ),
'panel' => 'footer', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );Now, we add the Custom field inside it using the following code:/* adding footer_custom_setting field */
Kirki::add_field( 'mk', array(
'type' => 'custom',
'settings' => 'footer_custom_setting',
'label' => __( 'Edit the footer', 'kirki' ),
'section' => 'footer_custom',
'default' => '', 'priority' => 10, ) );<?php
$footer_custom_code = Kirki::get_option( 'mk', 'footer_custom_setting' );
echo $footer_custom_code;
?>
Other notable points
There are a lot of options provided by Kirki like adding a logo for your theme inside the customizer and customizing the color of the customizer. We will also be discussing these in brief.
Adding a logo for your theme inside the customizer
By default, only the name of the website will be shown inside the customizer.
You can also add a logo of your theme using Kirki. This logo and description about your theme will be shown when the admin opens up the customizer. But you can add your own logo using the code below inside your theme-options.php file:
function mk_configuration() {
$args = array(
'logo_image' => get_template_directory_uri() . '/images/magnificient_kirki_logo.png',
'description' => __( 'This is the theme description. You can edit it in the Kirki configuration and add whatever you want here.', 'kirki' ),
'color_accent' => '#00bcd4',
'color_back' => '#455a64',
);
return $args;
}add_filter( 'kirki/config', 'mk_configuration' );
Now, on refreshing the customizer, we will see some noteable changes.
More about styling the customizer can be got from the wiki.
Registering new control types
You can register your new control types with Kirki. The syntax for registering and creating custom control types is:
/**
* Wrapper function to make sure our control is added where it needs to be added.
*/
function register_my_custom_control( $wp_customize ) {
/**
* The custom control class
*/
class Kirki_Controls_Notice_Control extends WP_Customize_Control {
public $type = 'notice';
public function render_content() { ?>
THE CONTROL CONTENT HERE
<?php
}
}
// Register our custom control with Kirki
add_filter( 'kirki/control_types', function( $controls ) {
$controls['notice'] = 'Kirki_Controls_Notice_Control';
} );}
add_action( 'customize_register', 'register_my_custom_control' );
You can then create new fields using your own control simply be defining notice as your field’s type.
Final notes
In this article, we learnt how we can create options for our theme using the Kirki toolkit. The possibilities summed up above are not the only ones. You can use Kirki to achieve much more. Feel free to fork my theme Magnificient_kirki which I made especially for this article only. This theme will give you a better idea about the implementation and the template structure which has been followed thorughout this article.
One more thing that you should note is that while useing the Theme Check plugin to check your theme, you might get some errors which may be due to the fact that I used all the files inside the Kirki folder. The errors are caused due to the markdown files which you can remove in order for successful passing of the tests. (I’ve updated the theme with only those files necessary in Github! Please have a look.)
Feel free to post any problems which you might have faced while implementing options with Kirki in the comments section and I’ll be happy to help you.
