Theme Customization API « WordPress Codex

 Theme Customization API « WordPress Codex

It is known that each WordPress template has a customization page through which you can control the WordPress template that you have installed on your site. But what if you want to add some other features, such as color control, adding images, or adding copyright in the footer, or perhaps adding a login button in the header.

But as we know that WordPress offers some default options for customization like site title , tagline and homepage options . But how can I add options to the WordPress template customization page?

In WordPress, there is a so-called WordPress template customization reference that is dedicated to programming such options from here  Theme Customization API .

What is meant by all of the above is the background colors section in the following image, for example:

Options for the WordPress theme customization page

Basic functions when adding options to the WordPress template customization page

  • add_panel : It is responsible for adding the main section with a new touch to the personalization page
  • add_section : is responsible for adding a section within the previous section
  • add_setting: is the one who adds the settings for this section
  • add_control : It is the one who adds the ability to control this section

Each of the previous sections also has specific connotations as follows:

add_section as in the following code

$wp_customize->add_section( 'wpmrj3_new_section' , array(
    'title'      => __( 'Colors', 'wpmrj3' ),
    'priority'   => 30,
) );

As we have noticed, in the code there are two functions, the first to give a name to the new section, and the second to give the place where it appears .

add_setting as in the following code:

$wp_customize->add_setting( 'wpmrj3_header_textcolor' , array(
    'default'   => '#000000',
    'transport' => 'refresh',
) );

As we note in the previous code, the wpmrj3_header_textcolor statement is an indication of the name of the add_setting function, and it is necessary to have a distinct name. There are certain names that you can use in some cases, such as setting to control the color or uploading an image, for example.. See the examples below.

1- As for the default option, here it takes the default value of the thing you want to add. If it is a color setting, for example, you can set the default color in case the user has not modified this option, or text for example if you want to add a customization setting for a specific text.

2- The transport option has two values, refresh, meaning instant preview when changing in the customization page, and the second value is postMessage, meaning the preview is only done when the page is refreshed after saving the setting in the customization page

add_control as in the following code:

$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'link_color', array(
    'label'      => __( 'Header Color ', 'mytheme' ),
	'section'    => 'wpmrj3_new_section',
	'settings'   => 'wpmrj3_header_textcolor',
) ) );

In the previous code and in the new line WP_Customize_Color_Control, here you find the name of the default function to add the color control code, for example, and this value cannot always be changed… You can also learn about the rest of the functions below the article in the examples.

As we also saw, the label option is the sub-name of the customization option in the section

In the section line here you put the name of the first function that we gave at the beginning when adding the section section, which in our example is wpmrj3_new_section

In the settings line, you also put here the name of the settings function that we put and in our example it is wpmrj3_header_textcolor

Drafting the complete code

We previously explained the functions and names used, but now we will get to know their use fully.

This code is for you to choose where to put it in the theme, for example, you can write it in the functions.php file, or you can create a new folder, for example, within the theme folder, and within this folder you create a new file named customizer.php

Then you can bring this file to functions.php using the following code:

require_once(get_template_directory().'/inc/customizer.php');

As for formulating the code, everything we wrote previously should be between two basic functions, namely function and add_filter

As in the following figure

function wpmrj3_control_options($wp_customize){
//هنا يوضع الكود بشكل كامل 
} 
add_action ('customize_register', 'wpmrj3_control_options');
 
  

The entire code above becomes:

 
<?php 
function wpmrj3_control_options($wp_customize){
//هنا يوضع الكود بشكل كامل 


    $wp_customize->add_section( 'wpmrj3_new_section' , array(
    'title'      => __( 'Background Colors', 'wpmrj3' ),
    'priority'   => 30,
) );
$wp_customize->add_setting( 'wpmrj3_header_textcolor' , array(
    'default'   => '#000000',
    'transport' => 'refresh',
) );
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'link_color', array(
    'label'      => __( 'Background Color', 'wpmrj3' ),
    'section'    => 'wpmrj3_new_section',
    'settings'   => 'wpmrj3_header_textcolor',
) ) );
} 
add_action ('customize_register', 'wpmrj3_control_options');
 
  

How to show and apply modifications to the WordPress template customization page

For our previous example, we created a new section called Background color, and this means the background color of all the site. To apply the changes to the site, we must also use another code to modify the layout. In this code, we will use both php and css as follows:

function wpmrj3_customize_css() { ?>
 
<?php }
add_action('wp_head' , 'wpmrj3_customize_css');

 

We created a new command earlier so that we can now apply css formatting to the Customize option section, which is the background color. The full format code will be:

function wpmrj3_customize_css() { ?>
 <style type="text/css">
 
    body{
        background-color:  <?php echo esc_html(get_theme_mod('wpmrj3_header_textcolor','#1f2024')); ?>;
    }
   </style>
 <?php }
add_action('wp_head' , 'wpmrj3_customize_css');

As we noticed, we injected the css code inside the previous command, which is to give the body a background color. As for the line following background-color: it is a default value that is always applied when extracting the value of the assignment option, and applying it in the site.

Examples of php codes to add options to the customization page of the wordpress template

1- Add the option to upload an image:

function wpmrj3_upload_control_options($wp_customize){
 $wp_customize->add_section('wpmrj3_upload_control_options_section' , array(
'title'=>__('Upload', 'wpmrj3'),
'priority'    => '19',
));

$wp_customize->add_setting('frontpage_image');
$wp_customize->add_control(new WP_Customize_Upload_Control($wp_customize,'frontpage_image_control',array(
 'label'      => __(' Upload Default', 'wpmrj3'),
 'section'    => 'wpmrj3_upload_control_options_section',
 'settings'   => 'frontpage_image',
 )));

 
} 
add_action ('customize_register', 'wpmrj3_upload_control_options');

2- Add the option to write text:

function wpmrj3_text_control_options($wp_customize){
 $wp_customize->add_section('wpmrj3_text_control_options_section' , array(
'title'=>__(' Text', 'wpmrj3'),
'priority'    => '19',
));

$wp_customize->add_setting('wpmrj3_text_control_options_settings', array(
 'default'        => ' Hello',
  'transport'=>'refresh'
) );
$wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'wpmrj3_text_control_options_settings_control', array(
'label'   => 'Write something here ',
'section'=>'wpmrj3_text_control_options_section',
'settings'   => 'wpmrj3_text_control_options_settings',
'type'=>'text'
)));
} 
add_action ('customize_register', 'wpmrj3_text_control_options');

2- Add a link option:

function wpmrj3_site_users_page_link($wp_customize){
 $wp_customize->add_section('wpmrj3_site_users_page_link_section' , array(
'title'=>__('Text', 'wpmrj3'),
'priority'    => '19',
));

$wp_customize->add_setting('wpmrj3_site_users_page_link', array(
 'default'        => '#',
));
$wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'wpmrj3_site_users_page_link_control', array(
'label'   => ' User User Page. ',
'section'=>'wpmrj3_site_users_page_link_section',
'settings'   => 'wpmrj3_site_users_page_link',
'type'=>'dropdown-pages'
)));
} 
add_action ('customize_register', 'wpmrj3_text_control_options');

As we noted in the previous examples, we used the add_control function, which is type . Here you will find in WordPress more than one option that you can use, which are as follows:

  •  text
  •  checkbox
  • radio 
  • select 
  • textarea
  •  dropdown-pages 
  • email 
  • url 
  • number
  •  hidden

The topic is not complicated, all you have to do is go to the WordPress reference page and read carefully to know what commands and functions you can use.