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.

1. text allows you to add a simple text input.
2. textarea allows you to add a textarea.
3. editor allows you to add a WYSIWYG editor.
4. radio allows you to add radio buttons.
5. checkbox allows you to add checkboxes.
6. color and color-alpha (supports transparency) allow you to select a color with a nice color picker.
7. background allows you to add a complete CSS background customizer.
8. palette allows you to add a color palette.
9. select allows you to add a dropdown menu.
10. select2 allows you to add a "better" selection menu, different from the default <option> HTML element.
11. select2-multiple allows you to add a selection menu with multiple choices. (Wild guess: This might be merged with the select2 field in the future.)
12. dropdown-pages allows you to add a dropdown menu listing the pages in the database.
13. upload allows you to add the native uploader.
14. image allows you to add the native image selector/uploader.
15. radio-image allows you to add images acting as radio buttons.
16. radio-buttonset allows you to add a button set acting as radio buttons.
17. number allows you to add an HTML5 number input.
18. slider allows you to add an HTML5 range slider.
19. multicheck allows you to add a list with multiple checkbox inputs.
20. switch allows you to add a "switch" button that acts like a checkbox, but prettier.
21. toggle allows you to add a "toggle" button that also acts like a checkbox.
22. sortable allows you to add a sortable list of checkbox controls.
23. custom allows 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 GenerateWP website!