WordPress Theme Development from Scratch Part 8 : Create Fie...

WordPress Theme Development from Scratch Part 8 : Create Fields for Theme Customizer API

Category: WordPress   Updated by Ryan Dhungel



In this part of WordPress Theme Development from Scratch series, We are going to learn how to Create Fields for Theme Customizer API and Implement them. This is an interesting feature of WordPress and this is what makes WordPress easy to use and customize for everyday people who don't want to get their hands dirty with coding and stuff.

We have already learned how to add Widgets functionality to the icon boxes in the part 7. If you haven't tried using it from the frontend, go to WordPress Dashboard Appearance/ Customize. There we have various theme customize options such as Site Identity, Menus, Widgets Section etc. We want to be able to Add a field there to control the Showcase Image for our front page and also the Heading, Description Text, Button text that sits in the middle and also the button link.

If you are jumping straight to this part, Just want to let you know that the front page Icon Boxes are the Widgets. We learned how to Create and Implement Widgets on part 7.


Requirements


Goals

  • Create Option Fields for Theme Customizer API


Create customizer.php

We will start off by creating a new folder called inc inside our theme folder. Then we will create a new file called customizer.php and save it inside that folder. Your folder directory should look like this:

wpbootstrap/inc/customizer.php


Now go to your functions.php and require that file, put it at the end.

// Theme Customizer
require get_template_directory(). '/inc/customizer.php';


Create customizer functions

Let's open up customizer.php and start writting functions. Here we are going to use customize_register function which is one of the many WordPress hooks available. Once you are comfortable working with the function below, I encourage you to explore more about wordpress hooks by visiting wordpress codex. First, Let me give you an introduction on what we are writting.

  • We will create a function my_customize_register and pass an object $wp_customize. Then we take that object and add_section to that by providing an array of options.
  • The array of options includes title with the text that you want to display and the name of our theme. For the description we use sprintf function and display the options info followed by the theme name with the priority of 130. Read more about add_action and priority in wordpress developers page.
  • Then we add_setting for heading and pass an array with the default input value of WP Bootstrap Theme, which will be visable in the customizer and also the options type of theme mode.
  • Now we also need to add_control with the heading and pass an array with labelsection and priority.


Here is the code:

<?php
function my_customize_register($wp_customize)
{
    // Showcase section
    $wp_customize->add_section('showcase', array(
            'title' => __('Showcase', 'wpbootstrap'),
            'description' => sprintf(__('Options for showcase', 'wpbootstrap')),
            'priority' => 130
        ));
    $wp_customize->add_setting('showcase_heading', array(
            'default' => _x('WP Bootstrap Theme', 'wpbootstrap'),
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control('showcase_heading', array(
            'label' => __('Heading', 'wpbootstrap'),
            'section' => 'showcase',
            'priority' => 2
        ));
}
add_action('customize_register', 'my_customize_register');

 

Remember my prefix we used in our functions.php ? we are just following that convention here. This function above speaks for itself. I suggest you to not copy but write it down to get a better understanding.


Once you have written it all, save it and go to the theme customizer to see if it made any difference. Go to Appearance/Customize. The Showcase option is right at the end. Now if you click on Showcase you will see that there is an Options for showcase and Heading with the default name.

See the screenshot below:

theme customizer


Now if you try to make any change to the heading text, you will notice the screen flashes. That means the showcase heading is coming to effect. Let's go ahead and do the same with the showcase text. We will basically copy the above code and modify a bit. Here is the code that you need to add to the above function.

    $wp_customize->add_setting('showcase_text', array(
            'default' => _x('This WordPress theme is created from scratch and using bootstrap.', 'wpbootstrap'),
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control('showcase_text', array(
            'label' => __('Text', 'wpbootstrap'),
            'section' => 'showcase',
            'priority' => 3
        ));


Now we have Text option available together with the heading. The next thing we want is a link option for the button and the text as well. Let's go through the similar process twice.

Here is the code you need to add to your function:

    $wp_customize->add_setting('btn_url', array(
            'default' => _x('http://kaloraat.com', 'wpbootstrap'),
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control('btn_url', array(
            'label' => __('Button URL', 'wpbootstrap'),
            'section' => 'showcase',
            'priority' => 4
        ));
    $wp_customize->add_setting('btn_text', array(
            'default' => _x('Learn More', 'wpbootstrap'),
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control('btn_text', array(
            'label' => __('Button Text', 'wpbootstrap'),
            'section' => 'showcase',
            'priority' => 5
        ));

 

theme customizer api options

Now if you reload the customize page, you should see Heading, Text, Button URL and Button Text options like the screenshot above.. Let's add an option for Image too.

    $wp_customize->add_setting('showcase_image', array(
            'default' => get_bloginfo('template_directory').'/img/showcase.jpg',
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control(new WP_Customize_Image_Control($wp_customize, 'showcase_image', array(
            'label' => __('Showcase Image', 'wpbootstrap'),
            'section' => 'showcase',
            'settings' => 'showcase_image',
            'priority' => 1
        )));

 

Okay Okay, I know It's a lot of code floating around. Here is the complete code from customizer.php.

 

<?php
function my_customize_register($wp_customize)
{
    // Showcase section
    $wp_customize->add_section('showcase', array(
            'title' => __('Showcase', 'wpbootstrap'),
            'description' => sprintf(__('Options for showcase', 'wpbootstrap')),
            'priority' => 130
        ));
    $wp_customize->add_setting('showcase_image', array(
            'default' => get_bloginfo('template_directory').'/img/showcase.jpg',
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control(new WP_Customize_Image_Control($wp_customize, 'showcase_image', array(
            'label' => __('Showcase Image', 'wpbootstrap'),
            'section' => 'showcase',
            'settings' => 'showcase_image',
            'priority' => 1
        )));
    $wp_customize->add_setting('showcase_heading', array(
            'default' => _x('WP Bootstrap Theme', 'wpbootstrap'),
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control('showcase_heading', array(
            'label' => __('Heading', 'wpbootstrap'),
            'section' => 'showcase',
            'priority' => 1
        ));
    $wp_customize->add_setting('showcase_text', array(
            'default' => _x('This WordPress theme is created from scratch and using bootstrap.', 'wpbootstrap'),
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control('showcase_text', array(
            'label' => __('Text', 'wpbootstrap'),
            'section' => 'showcase',
            'priority' => 2
        ));
    $wp_customize->add_setting('btn_url', array(
            'default' => _x('http://kaloraat.com', 'wpbootstrap'),
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control('btn_url', array(
            'label' => __('Button URL', 'wpbootstrap'),
            'section' => 'showcase',
            'priority' => 3
        ));
    $wp_customize->add_setting('btn_text', array(
            'default' => _x('Learn More', 'wpbootstrap'),
            'type' => 'theme_mod'
        ));
    $wp_customize->add_control('btn_text', array(
            'label' => __('Button Text', 'wpbootstrap'),
            'section' => 'showcase',
            'priority' => 4
        ));
    
}
add_action('customize_register', 'my_customize_register');


Create an Image Directory

Now that's it for the functions for now. Head over to your theme directory and create a folder called img. Find a beautiful wide image and name that showcase.jpg, it's the default image that we specified in the function above. Your image directory should look like this:

 

wpbootstrap/img/showcase.jpg


Now if you reload the customize page, you will see the default image and all other options we created so far.

Look at the screenshot below:

theme customizer image option


Conclusion

This is amazing, Isn't it? Until now you were probably wondering how those options lets us customize things in WordPress but now you know how all that works. I mean it is begining to look clear to you right? We learned how to create functions for Theme Customizer in this part, In the next part we will learn to Implement it.

I hope you are making a good progress with me on this WordPress theme development series. Please leave your comments below and use our forum for questions and answers.

Download source code from github 



Back to articles