In the previous tutorials we have learned how to configure and set some basic options with kirki customizer. In this tutorial we will learn how to create a complete WordPress theme options with this amazing customizer plugin. At the end of this tutorial, you will be able to customize or make your own complete WordPress theme options from scratch.
Requirements
This tutorial for WordPress theme developers, If you are not a developer, this tutorial is not for you. We assume you know the basic knowledge of working with WordPress kirki customizer, if you don’t, so please read the previous articles and introduction tutorials. Than come back and start creating a complete WordPress theme options. We will not go through installation and configuration of this plugin because we already did those things in previous articles. If you faced any problem, check the part one of this tutorials.
Step 1
Here is how we can include and configure this plugin in basic way.
include_once( dirname( __FILE__ ) . '/inc/plugins/kirki/kirki.php' );
function mytheme_kirki_configuration() {
return array( 'url_path' => get_stylesheet_directory_uri() . '/inc/plugins/kirki/' );
}
add_filter( 'kirki/config', 'mytheme_kirki_configuration' );
Step 2
Now we must add the panels and sections. To do that, first we create a function to wrap all panels and sections. For our example, we make one panel named, ” Theme Options”. Inside this panel, we create sections.
function up_kirki_section( $wp_customize ) {
/**
* Add panels
*/
$wp_customize->add_panel( 'up_theme_options', array(
'priority' => 10,
'title' => __( 'Theme Options', 'upplanet' ),
) );
/**
* Add sections
*/
$wp_customize->add_section( 'general_options', array(
'title' => __( 'General Options', 'upplanet' ),
'priority' => 10,
'panel' => 'up_theme_options',
) );
$wp_customize->add_section( 'header_options', array(
'title' => __( 'Header Options', 'upplanet' ),
'priority' => 20,
'panel' => 'up_theme_options',
) );
$wp_customize->add_section('layout_options',array(
'title' => __('Layouts Options','upplanet'),
'priority' => 30,
'panel' => 'up_theme_options',
));
$wp_customize->add_section('slide_options',array(
'title' => __('Slide Options','upplanet'),
'priority' => 30,
'panel' => 'up_theme_options',
));
$wp_customize->add_section('page_options',array(
'title' => __('Page Options','upplanet'),
'priority' => 30,
'panel' => 'up_theme_options',
));
$wp_customize->add_section('single_options',array(
'title' => __('Single Page','upplanet'),
'priority' => 40,
'panel' => 'up_theme_options',
));
$wp_customize->add_section('footer_options',array(
'title' => __('Footer Options','upplanet'),
'priority' => 50,
'panel' => 'up_theme_options',
));
}
add_action( 'customize_register', 'up_kirki_section' );
We append each section we create to up_theme_options panel. Until now, you might not see anything in the WordPress customizer page. It will show-up when we add the fields and options. The last line will hook the panels to customize_register. Now we have almost a complete WordPress theme options. Let’s add options and fields.
Step 3
It’s up to you, what you need and what you want to add in your theme options. We will add one fields for each section just to show you the example. Than you can customize it for your own theme. To add fields, we need to create a new function and hook it to kirki/fields.
Here is a basic example. let’s add a favicon uploader fields in general section.
function up_kirki_fields( $wp_customize ) {
/*General Options*/
$fields[] = array(
'type' => 'image',
'settings' => 'fav_icon',
'label' => __( 'Favicon', 'upplanet' ),
'description' => __( 'Upload your site favicon here', 'upplanet' ),
'section' => 'general_options',
'default' => '',
'priority' => 10,
);
return $fields;
}
add_filter( 'kirki/fields', 'up_kirki_fields' );
$fields[] is an array that will contain all the fields for all sections. And at the end of function, we return the $fields.
the last line will hook the up_kirki_fields function to kirki fields.
Step 4
Let’s add one field for each section we have created. We will use different input types to show you how we can use them. After that we will write the complete WordPress theme options code.
Here is the complete code for fields function.
function up_kirki_fields( $wp_customize ) {
/*General Options*/
$fields[] = array(
'type' => 'image',
'settings' => 'fav_icon',
'label' => __( 'Favicon', 'upplanet' ),
'description' => __( 'Upload your site favicon here', 'upplanet' ),
'section' => 'general_options',
'default' => '',
'priority' => 10,
);
// Header Options
$fields[] = array(
'type' => 'radio-image',
'setting' => 'header_hero',
'label' => __( 'Choose to show slide or text in header', 'upplanet' ),
'section' => 'header_options',
'default' => 'slide',
'priority' => 10,
'choices' => array(
'slide' => trailingslashit( get_template_directory_uri() ) . 'images/header-slide.png',
'text' => trailingslashit( get_template_directory_uri() ) . 'images/header-text.png',
),
);
// Layouts Options
$fields[] = array(
'type' => 'radio-image',
'setting' => 'up_layout',
'label' => __( 'Site Layout', 'upplanet' ),
'description' => __( 'Decide which layout you want for your site', 'upplanet' ),
'section' => 'layout_options',
'default' => 'sidebar-right',
'priority' => 10,
'choices' => array(
'sidebar-right' => trailingslashit( get_template_directory_uri() ) . 'images/layout-right-side.png',
'sidebar-left' => trailingslashit( get_template_directory_uri() ) . 'images/layout-left-side.png',
'right-left' => trailingslashit( get_template_directory_uri() ) . 'images/right-left-side.png',
),
);
// Slide Options
$fields[] = array(
'type' => 'radio',
'settings' => 'slide_query',
'label' => __( 'What to Query in Slide', 'upplanet' ),
'section' => 'slide_options',
'default' => 'recent-posts',
'priority' => 10,
'choices' => array(
'most-commented' => esc_attr__( 'Query most commented posts', 'upplanet' ),
'recent-posts' => esc_attr__( 'Query most recent posts', 'upplanet' ),
),
);
/*Page Options*/
$fields[] = array(
'type' => 'slider',
'settings' => 'page_hero',
'label' => esc_attr__( 'Page Header Hieght', 'upplanet' ),
'section' => 'page_options',
'default' => 120,
'choices' => array(
'min' => '100',
'max' => '400',
'step' => '1',
),
);
/*Single Post*/
$fields[] = array(
'type' => 'checkbox',
'settings' => 'show_single_social',
'label' => __( 'Show Social Share', 'upplanet' ),
'section' => 'single_options',
'default' => '1',
'priority' => 10,
);
// Footer Options
$fields[] = array(
'type' => 'textarea',
'settings' => 'copy_right',
'label' => __( 'Footer Copyright Note', 'upplanet' ),
'section' => 'footer_options',
'default' => esc_attr__( 'Theme By <a href="http://www.upplanet.com">Upplanet </a>', 'upplanet' ),
'priority' => 10,
'sanitize_callback' => 'do_not_filter_anything',
);
return $fields;
}
add_filter( 'kirki/fields', 'up_kirki_fields' );
Complete WordPress Theme Options
To wrap-up the complete WordPress theme options tutorial, let’s write the complete code snippet.
function do_not_filter_anything( $value ) {
return $value;
}
include_once( dirname( __FILE__ ) . '/inc/plugins/kirki/kirki.php' );
function mytheme_kirki_configuration() {
return array( 'url_path' => get_stylesheet_directory_uri() . '/inc/plugins/kirki/' );
}
add_filter( 'kirki/config', 'mytheme_kirki_configuration' );
function up_kirki_section( $wp_customize ) {
/**
* Add panels
*/
$wp_customize->add_panel( 'up_theme_options', array(
'priority' => 10,
'title' => __( 'Theme Options', 'upplanet' ),
) );
/**
* Add sections
*/
$wp_customize->add_section( 'general_options', array(
'title' => __( 'General Options', 'upplanet' ),
'priority' => 10,
'panel' => 'up_theme_options',
) );
$wp_customize->add_section( 'header_options', array(
'title' => __( 'Header Options', 'upplanet' ),
'priority' => 20,
'panel' => 'up_theme_options',
) );
$wp_customize->add_section('layout_options',array(
'title' => __('Layouts Options','upplanet'),
'priority' => 30,
'panel' => 'up_theme_options',
));
$wp_customize->add_section('slide_options',array(
'title' => __('Slide Options','upplanet'),
'priority' => 30,
'panel' => 'up_theme_options',
));
$wp_customize->add_section('page_options',array(
'title' => __('Page Options','upplanet'),
'priority' => 30,
'panel' => 'up_theme_options',
));
$wp_customize->add_section('single_options',array(
'title' => __('Single Page','upplanet'),
'priority' => 40,
'panel' => 'up_theme_options',
));
$wp_customize->add_section('footer_options',array(
'title' => __('Footer Options','upplanet'),
'priority' => 50,
'panel' => 'up_theme_options',
));
}
add_action( 'customize_register', 'up_kirki_section' );
function up_kirki_fields( $wp_customize ) {
/*General Options*/
$fields[] = array(
'type' => 'image',
'settings' => 'fav_icon',
'label' => __( 'Favicon', 'upplanet' ),
'description' => __( 'Upload your site favicon here', 'upplanet' ),
'section' => 'general_options',
'default' => '',
'priority' => 10,
);
// Header Options
$fields[] = array(
'type' => 'radio-image',
'setting' => 'header_hero',
'label' => __( 'Choose to show slide or text in header', 'upplanet' ),
'section' => 'header_options',
'default' => 'slide',
'priority' => 10,
'choices' => array(
'slide' => trailingslashit( get_template_directory_uri() ) . 'images/header-slide.png',
'text' => trailingslashit( get_template_directory_uri() ) . 'images/header-text.png',
),
);
// Layouts Options
$fields[] = array(
'type' => 'radio-image',
'setting' => 'up_layout',
'label' => __( 'Site Layout', 'upplanet' ),
'description' => __( 'Decide which layout you want for your site', 'upplanet' ),
'section' => 'layout_options',
'default' => 'sidebar-right',
'priority' => 10,
'choices' => array(
'sidebar-right' => trailingslashit( get_template_directory_uri() ) . 'images/layout-right-side.png',
'sidebar-left' => trailingslashit( get_template_directory_uri() ) . 'images/layout-left-side.png',
'right-left' => trailingslashit( get_template_directory_uri() ) . 'images/right-left-side.png',
),
);
// Slide Options
$fields[] = array(
'type' => 'radio',
'settings' => 'slide_query',
'label' => __( 'What to Query in Slide', 'upplanet' ),
'section' => 'slide_options',
'default' => 'recent-posts',
'priority' => 10,
'choices' => array(
'most-commented' => esc_attr__( 'Query most commented posts', 'upplanet' ),
'recent-posts' => esc_attr__( 'Query most recent posts', 'upplanet' ),
),
);
/*Page Options*/
$fields[] = array(
'type' => 'slider',
'settings' => 'page_hero',
'label' => esc_attr__( 'Page Header Hieght', 'upplanet' ),
'section' => 'page_options',
'default' => 120,
'choices' => array(
'min' => '100',
'max' => '400',
'step' => '1',
),
);
/*Single Post*/
$fields[] = array(
'type' => 'checkbox',
'settings' => 'show_single_social',
'label' => __( 'Show Social Share', 'upplanet' ),
'section' => 'single_options',
'default' => '1',
'priority' => 10,
);
// Footer Options
$fields[] = array(
'type' => 'textarea',
'settings' => 'copy_right',
'label' => __( 'Footer Copyright Note', 'upplanet' ),
'section' => 'footer_options',
'default' => esc_attr__( 'Theme By <a href="http://www.upplanet.com">Upplanet </a>', 'upplanet' ),
'priority' => 10,
'sanitize_callback' => 'do_not_filter_anything',
);
return $fields;
}
add_filter( 'kirki/fields', 'up_kirki_fields' );
We have added some more line to complete WordPress theme options.
do_not_filter_anything
If you don’t want any field to filter through html special char you can add this callback. Though it’s not a complete WordPress theme options, if you change and add a little more options, you can make it a complete WordPress theme options for your own.
How to use the value.
It’s pretty simple. Every field we create has a settings identifier, just echo it where you want to display or use the option value.
echo get_theme_mod('setting_identifier');
Conclusion.
I hope, it help you make your next complete WordPress theme options settings. If you want to know more about kirki, I recommend join the github issues about this powerful plugin. If you have any questions or problem, feel free to ask it bellow.
That use was very useful, thank you