In a previous tutorial I wrote about how you can create your own theme options page in Wordpress. Well now this tutorial is no longer needed for themes anyway. For years the only way to update and customise the Wordpress theme was to create a themes option panel. Premium Wordpress theme developers have been marketing this features for just as long building theme option panels which will do everything to customise your theme, it will change styling, functionality, SEO, post type, shortcodes etc. Since version 3.4 things have changed, I can't think of a good reason to have a theme options page at all, any functionality that you used to put in there can either be placed in the new theme customiser page or in plugins. The theme customiser will take care of all styling for your theme and SEO, post types, shortcodes should be handled with plugins. The benefit of having these settings in plugins and not on theme options is if you change your theme you still keep your SEO settings, you keep your post types and you keep your shortcodes. If these settings are in your theme settings and you change your theme you've lost everything.
What Is The Theme Customiser?
The theme customiser was added in version 3.4 it allows developers to create a page where admin users can edit the style of the theme and see a preview of the changes in real time without changing the live site. Before if you were using the theme option panel you could change the background colour of your site but you won't know what it looks like until you save the settings and go to your site. But as the colour is already saved everyone will be able to see the colour change even if you selected the wrong colour. If you have a high traffic site a couple hundred people could be on your site and watch you play around with the styles until you get the settings right. With the theme customiser you can just stay in the admin area and see your changes in real-time in a preview panel, without changing the live site.
The advantages of using this over the theme options page is that you can make small styling changes to your site without affecting the live site. As the theme customiser is still quite new you will find that there aren't many themes that support this feature and will continue to use a theme options panel. This is mainly because people have created nice frameworks to easily create a theme option panel with limited code.
How Theme Customiser Works?
The theme customiser is split up into 4 areas. - Theme Customiser Manager
- Customiser Settings
- Customiser Control
- Customiser Sections
The customiser API works by using the theme customiser manager, the manager class has methods to work with sections, settings, and controls. When using the theme customiser API you will have to use the Wordpress action customize_register, this action will automatically provide you with an instance of the WP_Customize_Manager class.
function theme_customiser( $wp_customize_manager )
{
// Add all your settings, sections and controls on to the $wp_customize_manager
}
add_action( 'customize_register', 'theme_customiser' );
The above code is an example of how to create an instance of the WP_Customize_Manager class, this object is passed as a parameter on the customize_register action. This object should be used to set all the sections, settings and controls for the theme customiser page.
Sections
Sections will split the settings into different groups to make it easier to display the settings. For example you can have a background section where you can place settings for background colours or background images. The method you can use on the sections are: - get_section( $id ) - Gets the section by section ID.
- remove_section( $id ) - Removes the section by section ID.
- add_section( $id , array() ) - Adds a new section to the customiser manager, the first parameter is the ID of the section, the second parameter is an array of options for the section.
When getting a section you use the get_section() method, this will return a section object.
$section = $wp_customize_manager->get_section( 'id' );
To remove this section from the manager you need to use the remove_section() method.
$wp_customize_manager->remove_section( 'id' );
The values you need to set when adding the section are: the section ID, title, description and priority.
$wp_customize_manager->add_section( 'manager', array(
'title' => 'Customiser Manager',
'description' => 'Example of adding customiser section.',
) );
Settings
The setting is the component that will be used on the form for the theme customiser. The settings will live inside the sections of the page. They are used to store data in the database and change the settings of the theme styles.
- get_setting( $id ) - Get the setting by setting ID.
- remove_setting( $id ) - Removes the setting by setting ID.
- add_setting( $id , array() ) - Adds a new setting to the customiser manager, the first parameter is the ID of the setting, the second parameter is an array of options for the setting.
To get the setting of a section you need to use the get_setting() method, this will return a setting object populated with the values of the setting.
$setting = $wp_customize_manager->get_setting( 'id' );
To remove a setting from the theme customiser all you have to do is use the remove_setting() method.
$wp_customize_manager->remove_setting( 'id' );
To add a setting you need to use the add_setting() method.
$wp_customize_manager->add_setting( 'id', array('default' => 'Default Value',
'type' => 'theme_mod',
'capability' => 'manage_options',
'transport' => 'refresh' ) );
There are 4 options you use in the array of the add_setting() method. - Default - The default value used on the option.
- Type - The type setting you are creating can either be 'option' or 'theme_mod'.
- Capability - The capabilities a user must have to change the options on the theme.
- Transport - This is the transport that will provide you with a live preview of the theme. The default value is refresh this will refresh the entire preview panel. The other value you can use is postMessage this should be used for when you are changing HTML or CSS as you can use Javascript to change the preview.
Control
The control component is used to control which settings are added on to a specific section. The control is used to define the additional settings for this one control and render it on the screen. The benefit of this class is that you can reuse settings in sections which reduces the amount of code you need to write. There are 3 main methods for controls, get_control(), remove_control() and add_control(). - get_control( $id ) - Get the control by control ID.
- remove_control( $id ) - Removes the section by control ID.
- add_control( $id , array() ) - Adds a new control to the customiser manager, the first parameter is the ID of the control, the second parameter is an array of options for the control.
To get a control we just need to use the get_control() method with the control ID.
$wp_customize_manager->get_control( $id );
If you want to remove a control from the customiser page just use the remove_control() method with the control ID.
$wp_customize_manager->remove_control( $id );
To add a control we need to use the add_control() method with a ID and an array of settings, these settings are: - Label - The text to be used in the setting.
- Settings - The ID of the setting to be used, you can leave this blank and it will use the same ID as the control.
- Section - The ID of the section that you are adding the setting.
- Type - The type of setting to be used, can be text, checkbox, radio, select, dropdown-pages
- Choices - A set of options for the select box or radio buttons. Be careful using this property as it will be removed in future releases.
- Priority - The order of the settings, the lower the setting the earlier the setting will appear.
Default Controls
There are a number of different controls that already exist as part as the theme customiser. These are some of the default controls that you can already use on the theme customiser. Title Tagline
$this->add_section( 'title_tagline', array(
'title' => __( 'Site Title & Tagline' ),
'priority' => 20,
) );
Colors
$this->add_section( 'colors', array(
'title' => __( 'Colors' ),
'priority' => 40,
) );
Header Image
$this->add_section( 'header_image', array(
'title' => __( 'Header Image' ),
'theme_supports' => 'custom-header',
'priority' => 60,
) );
Background Image
$this->add_section( 'background_image', array(
'title' => __( 'Background Image' ),
'theme_supports' => 'custom-background',
'priority' => 80,
) );
Navigation
$this->add_section( 'nav', array(
'title' => __( 'Navigation' ),
'theme_supports' => 'menus',
'priority' => 100,
'description' => sprintf( _n('Your theme supports %s menu. Select which menu you would like to use.', 'Your theme supports %s menus. Select which menu appears in each location.', $num_locations ), number_format_i18n( $num_locations ) ) . "\n\n" . __('You can edit your menu content on the Menus screen in the Appearance section.'),
) );
Static Front Page
$this->add_section( 'static_front_page', array(
'title' => __( 'Static Front Page' ),
// 'theme_supports' => 'static-front-page',
'priority' => 120,
'description' => __( 'Your theme supports a static front page.' ),
) );
Custom Controls At the moment of writing this there are only a couple of custom controls that can be used to extend the functionality of the add_control() method. For example using these custom control you can add a setting for colour wheel, upload from the media library, upload images, select a new background image or select a new header image. To use these controls you need to add the following classes in the add_control() method.
Add Colour Wheel To Theme Customiser
To add a colour wheel to the theme customiser create a new instance of the WP_Customize_Color_Control() and pass this in as the parameter for the add_control() method.
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize_manager, 'link_color', array(
'label' => __( 'Header Color', 'mytheme' ),
'section' => 'your_section_id',
'settings' => 'your_setting_id',
) ) );
Add Media Upload To Theme Customiser
To add a setting to upload media to the theme use this code snippet.
$wp_customize->add_control( new WP_Customize_Upload_Control( $wp_customize_manager, 'upload_media', array(
'label' => __( 'Media Upload', 'mytheme' ),
'section' => 'your_section_id',
'settings' => 'your_setting_id',
) ) );
Add Image Upload To Theme Customiser
To add a setting to upload images to the theme use this code snippet.
$wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize_manager, 'upload_images', array(
'label' => __( 'Image Upload', 'mytheme' ),
'section' => 'your_section_id',
'settings' => 'your_setting_id',
) ) );
Add Background Images To Theme Customiser
To add a setting to upload background images to the theme use this code snippet.
$wp_customize->add_control( new WP_Customize_Background_Image_Control( $wp_customize_manager, 'background_image', array(
'label' => __( 'Background Image', 'mytheme' ),
'section' => 'your_section_id',
'settings' => 'your_setting_id',
) ) );
Add Header Image To Theme Customiser
To add a setting to add a header image to the theme use this code snippet.
$wp_customize->add_control( new WP_Customize_Header_Image_Control( $wp_customize_manager, 'header_image', array(
'label' => __( 'Header Image', 'mytheme' ),
'section' => 'your_section_id',
'settings' => 'your_setting_id',
) ) );
Building A Theme Customiser Page
Now we understand how the theme customizer page is made up and how you use the customizer manager to add settings and sections then use controls to add them together. We are now going to create an example section of the default settings available on the customizer page. I prefer working with classes, so the following code will consist of a PHP class which we will start by including it from functions.php file.
include 'theme_customizer.php';
Create a new file in your template folder and save is as theme_customizer.php and copy the following code. This will add a new menu item to the appearance menu for the customizer page and adds a new section for the default controls.
<?php
new theme_customizer();
class theme_customizer
{
public function __construct()
{
add_action ('admin_menu', array(&$this, 'customizer_admin'));
add_action( 'customize_register', array(&$this, 'customize_manager_demo' ));
}
/**
* Add the Customize link to the admin menu
* @return void
*/
public function customizer_admin() {
add_theme_page( 'Customize', 'Customize', 'edit_theme_options', 'customize.php' );
}
/**
* Customizer manager demo
* @param WP_Customizer_Manager $wp_manager
* @return void
*/
public function customize_manager_demo( $wp_manager )
{
$this->demo_section( $wp_manager );
}
public function demo_section( $wp_manager )
{
$wp_manager->add_section( 'customiser_demo_section', array(
'title' => 'Default Demo Controls',
'priority' => 35,
) );
// Textbox control
$wp_manager->add_setting( 'textbox_setting', array(
'default' => 'default_value',
) );
$wp_manager->add_control( 'textbox_setting', array(
'label' => 'Text Setting',
'section' => 'customiser_demo_section',
'type' => 'text',
'priority' => 1
) );
// Checkbox control
$wp_manager->add_setting( 'checkbox_setting', array(
'default' => '1',
) );
$wp_manager->add_control( 'checkbox_setting', array(
'label' => 'Checkbox Setting',
'section' => 'customiser_demo_section',
'type' => 'checkbox',
'priority' => 2
) );
// Radio control
$wp_manager->add_setting( 'radio_setting', array(
'default' => '1',
) );
$wp_manager->add_control( 'radio_setting', array(
'label' => 'Radio Setting',
'section' => 'customiser_demo_section',
'type' => 'radio',
'choices' => array("1", "2", "3", "4", "5"),
'priority' => 3
) );
// Select control
$wp_manager->add_setting( 'select_setting', array(
'default' => '1',
) );
$wp_manager->add_control( 'select_setting', array(
'label' => 'Select Dropdown Setting',
'section' => 'customiser_demo_section',
'type' => 'select',
'choices' => array("1", "2", "3", "4", "5"),
'priority' => 4
) );
// Dropdown pages control
$wp_manager->add_setting( 'dropdown_pages_setting', array(
'default' => '1',
) );
$wp_manager->add_control( 'dropdown_pages_setting', array(
'label' => 'Dropdown Pages Setting',
'section' => 'customiser_demo_section',
'type' => 'dropdown-pages',
'priority' => 5
) );
// Color control
$wp_manager->add_setting( 'color_setting', array(
'default' => '#000000',
) );
$wp_manager->add_control( new WP_Customize_Color_Control( $wp_manager, 'color_setting', array(
'label' => 'Color Setting',
'section' => 'customiser_demo_section',
'settings' => 'color_setting',
'priority' => 6
) ) );
// WP_Customize_Upload_Control
$wp_manager->add_setting( 'upload_setting', array(
'default' => '',
) );
$wp_manager->add_control( new WP_Customize_Upload_Control( $wp_manager, 'upload_setting', array(
'label' => 'Upload Setting',
'section' => 'customiser_demo_section',
'settings' => 'upload_setting',
'priority' => 7
) ) );
// WP_Customize_Image_Control
$wp_manager->add_setting( 'image_setting', array(
'default' => '',
) );
$wp_manager->add_control( new WP_Customize_Image_Control( $wp_manager, 'image_setting', array(
'label' => 'Image Setting',
'section' => 'customiser_demo_section',
'settings' => 'image_setting',
'priority' => 8
) ) );
}
}
?>
Use The Settings In The Theme
The whole point of creating a theme customiser page is so you can use these values in a way to customise your theme. To get settings from the setting API you can use the function get_theme_mod().
<?php get_theme_mod( $name, $default ) ?>
The first parameter is the name you give to your setting from the theme customiser page and the second parameter is the default value which will be used if the setting is not set. This value can be used to set the font colour in your CSS style tag.
function custom_colors()
{
?>
body {
color: #<?php echo get_theme_mod( 'background_color' ); ?>;
}
<?php
}
add_action( 'wp_head', 'custom_colors');
Conclusion
From this tutorial you would of learnt how to create your own theme customiser page with a number of settings added to your own section of the page. You would of learnt how to customise these settings so that you can use the default types to input the data you require. You have also seen how you can create your own custom controls to display exactly the data you need. In a future tutorial I will create a new custom control to add a dropdown populated with the current categories. Hopefully this tutorial has shown you that you can use the theme customiser as a replacement for bloated theme options panels and that to use this page to handle the styling of the theme with a real time preview of your page.