Welcome to the second part of the "Toolbox of the Smart WordPress Developer" series! In this part, we're going to go through Kirki, a great Customizer toolkit for WordPress theme developers.
Let's begin!
A Word on the Customizer
WordPress version 3.4 introduced a new API called the Theme Customization API and the "Theme Customizer" screen. (In version 4.1, the word "Theme" was dropped since it's not exclusively a "theme customizer".) It allows us to add customization options in the Appearance > Customize menu, with an opportunity to change theme settings simultaneously while previewing the website.
It didn't create much hype at first, but the community adopted it over time, and we gradually got more and more excited about this handy API. Over two years after its release, the Customizer API has evolved into a wonderful utility that even lets us publish posts and customize the login screen.
It's not an overstatement to say that Customizer is one of the most valuable APIs of WordPress because of its ability to completely change users' experience.
If you want to learn more on this subject, check out our series on the Customizer, written by Lee Pham.
Enter Kirki: Easy Development for the Customizer Screen
Kirki is a great tool to improve the experience of a theme's users. It focuses solely on theme customization and extends the default Customizer controls with toggles, range inputs and images as radio buttons.
Once you get to know how it works, building a theme customization screen will be easier than ever.
A Call to Action: Kirki is translation-ready and needs your help to translate this open-source project into different languages. I'm going to handle the Turkish translation, and it would be great if you could help translate Kirki into your language. If you want to contribute, contact Aristeides Stathopoulos, author of Kirki, for details.
Embedding Kirki in Your Theme and Configuring It
Bundling your theme with Kirki is very easy, actually. You just need to download the latest version from GitHub, extract the contents into a folder in your theme, and include the main plugin file (by using the include_once() function) in your theme's functions.php file.
Here's an example:
<?php include_once( dirname( __FILE__ ) . '/path/to/kirki/kirki.php' ); ?>
Piece of cake, isn't it? Below that, you can create a configuration to avoid conflicts with other themes or plugins that use Kirki as well:
<?php
Kirki::add_config( 'my_theme', array(
'capability' => 'edit_theme_options',
'option_type' => 'option',
'option_name' => 'my_theme',
) );
?>
Done!
Using Kirki in Your Theme
Now we've learned about how to embed and configure Kirki in our themes, it's time to see some examples of how to build our theme customization page.
Let's start with the basics. Here's the code of a basic installation with some panels and sections but without any control fields:
<?php
/**
* Add panels
*/
Kirki::add_panel( 'panel_id', array(
'priority' => 10,
'title' => __( 'My Title', 'textdomain' ),
'description' => __( 'My Description', 'textdomain' ),
) );
/**
* Add sections
*/
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.
) );
?>
Now, let's see about the control fields Kirki provides.
Control Field Types of Kirki
After creating your panels and sections, you can fill in the sections with "control fields". Here's the code to add a field inside a section:
<?php
Kirki::add_field( 'my_theme', array(
'type' => 'text',
'setting' => 'text_demo',
'label' => __( 'This is the label', 'kirki' ),
'description' => __( 'This is the control description', 'kirki' ),
'help' => __( 'This is some extra help text.', 'kirki' ),
'section' => 'my_section',
'default' => __( 'This is some default text', 'kirki' ),
'priority' => 10,
) );
?>
As I said before, Kirki extends the default control fields list with new ones. For the sake of writing a more "complete" tutorial, I will include the core control fields as well as Kirki's additional control fields.
-
textallows you to add a simple text input. -
textareaallows you to add a textarea. -
editorallows you to add a WYSIWYG editor. -
radioallows you to add radio buttons. -
checkboxallows you to add checkboxes. -
colorandcolor-alpha(supports transparency) allow you to select a color with a nice color picker. -
backgroundallows you to add a complete CSS background customizer. -
paletteallows you to add a color palette. -
selectallows you to add a dropdown menu. -
select2allows you to add a "better" selection menu, different from the default<option>HTML element. -
select2-multipleallows you to add a selection menu with multiple choices. (Wild guess: This might be merged with theselect2field in the future.) -
dropdown-pagesallows you to add a dropdown menu listing the pages in the database. -
uploadallows you to add the native uploader. -
imageallows you to add the native image selector/uploader. -
radio-imageallows you to add images acting as radio buttons. -
radio-buttonsetallows you to add a button set acting as radio buttons. -
numberallows you to add an HTML5 number input. -
sliderallows you to add an HTML5 range slider. -
multicheckallows you to add a list with multiple checkbox inputs. -
switchallows you to add a "switch" button that acts like a checkbox, but prettier. -
toggleallows you to add a "toggle" button that also acts like a checkbox. -
sortableallows you to add a sortable list of checkbox controls. -
customallows you to add a custom control field, which is basically any valid HTML code fragment.
Styling Kirki
Kirki has some pretty cool settings for you to make a customized Customizer for your theme. You can display a logo above the control fields, set a different color scheme for the Customizer and so on.
-
logo_image: Specifies the logo image URL. -
description: Specifies a description text that will be displayed upon clicking the logo. -
color_active: Specifies the "active" color for menu items, help buttons and such. -
color_light: Specifies the "secondary" color for disabled and inactive controls. -
color_select: Specifies the "selected" color for, well, selected stuff. -
color_accent: Specifies the "accent" color that's used on slider controls and image selects. -
color_back: Specifies the background color for the Customizer. -
url_path: Specifies the URL path for Kirki, used for loading CSS files in its/assets/folder. -
stylesheet_id: The stylesheet ID to set as the handle in CSS enqueueing processes.
To set these style options, you will need to use the kirki/config filter. Here's an example of how to configure Kirki:
<?php
/**
* Styling configuration for the Kirki Customizer
*/
function kirki_demo_configuration_sample_styling( $config ) {
$config['logo_image'] = 'http://kirki.org/img/kirki-new-logo-white.png';
$config['description'] = __( 'The theme description.', 'kirki' );
$config['color_accent'] = '#00bcd4';
$config['color_back'] = '#455a64';
$config['width'] = '20%';
return $config;
}
add_filter( 'kirki/config', 'kirki_demo_configuration_sample_styling' );
?>
Getting the Values
You have to use the values in your theme that Kirki stores, right? Here's how:
<?php $value = Kirki::get_option( $config_id, $option_id ); ?>
Simple as that. Of course, you still can use the core get_option() and get_theme_mod() functions.
Wrapping Up for Today
Tools like this make WordPress even more user-friendly and easy to develop, don't you think? As I said in the series introduction, the power of WordPress comes from its community, and tools like this are the key to community growth. Kirki offers more than I wrote in this tutorial, and Ari (the author) promises that he will continue developing Kirki for, in his words, as long as it takes.
What do you think about Kirki? Shoot your thoughts in the Comments section below. And if you liked the article, don't forget to share it with your friends!
See you in the next part where we'll be covering the Theme Check plugin.
Comments