Creating Your Own Theme Customiser Custom Controls

In a previous tutorial I wrote about the new theme customiser page and how you can use this to change the styling and functionality of your Wordpress theme. In this tutorial we investigated multiple options you can use to customise this page and use these setting within your theme. As the theme customiser page is still quite new there aren't that many controls to use on your page. This is where you will need to create your own custom controls. There may be settings which you will want to use over and over again, this is where creating your own * custom controls* will come in handy. When you create you own control controls you can reuse this functionality in other areas of your customiser page. In this tutorial we are going to build are own custom controls to display all the categories in your Wordpress site. All the custom controls you make are going to be classes, therefore if you don't understand object oriented programming with PHP you might find this tutorial a bit tricky to understand. First we start off by creating a class for our custom control, this class needs to extend (inherit) from the * WP_Customiser_control* so you need to make sure this class exists before you define your new class.

if (class_exists('WP_Customize_Control'))
{
     class Category_Dropdown_Custom_control extends WP_Customize_Control
     {

     }
}

As your class inherits from WP_Customize_Control you will have access to override a number of methods to perform the tasks you want. - enqueue() - Add scripts or styles to the class

• value() - Get a setting value
• to_json() - Pass the settings parameters to the javascript by JSON.
• check_capabilities() - Checks if the theme and user has the capabilities of the control.
• maybe_render() - Checks if the correct capabilities are set to render the control.
• render() - Will render the control on the page by calling render_content().
• render_content() - Method used to render the control.

For this control we only need to change the render_content() method and get the categories. To get all the categories on your Wordpress site you need to use the function get_categories(). This function will return an array of category objects which you can loop through to create your select options.

if (class_exists('WP_Customize_Control'))
{
     class Category_Dropdown_Custom_control extends WP_Customize_Control
     {
          public function render_content()
           {

                ?>
                    <label>
                      <span class="customize-category-select-control"><?php echo esc_html( $this->label ); ?></span>

                      <?php wp_dropdown_categories(array('hide_empty' => 0, 'id' => $this->id)); ?>
                    </label>
                <?php
           }
     }
}

Now this custom control is created we can go to the theme customiser manager and add this to a customiser manager control.

require_once('category_dropdown_custom_control.php');

        $wp_manager->add_section( 'category_demo_section', array(
            'title'          => 'Category Controls',
            'priority'       => 99,
        ) );

        $wp_manager->add_setting( 'category_dropdown_setting', array(
            'default'        => 'Dropdown displaying all the categories',
        ) );

        $wp_manager->add_control( new Category_Dropdown_Custom_control( $wp_manager, 'category_dropdown_setting', array(
            'label'   => 'Select A Category',
            'section' => 'category_demo_section',
            'settings'   => 'category_dropdown_setting',
        ) ) );

If you go to your theme customiser you will see a new control which is a drop down box populated with all the categories from your website. As the theme customiser gets older Wordpress should release more built in theme customiser controls, until then have a look at this Github repository I have created some extra custom controls to use for your theme customiser page. If you have made any other controls please contribute to the Github Repository hopefully together we can build a good library of controls to use. Custom Controls