Add Header Image Title using API Customizer

Have you looked at the Customizer section of the Theme Handbook? It stands as the official Customizer documentation, though admittedly it’s quite terse and difficult to understand. If you can manage to add a simple, basic setting without getting into contextual controls and selective refresh, you’ll be off to a good start. Build upon that basic implementation to get to what you really need.

All the customizer code can go in your theme’s functions.php or any other theme code that is included or required through functions.php. You mainly need to add a setting and a related control. The setting will likely be stored as a theme_mod, so you would use get_theme_mod() to retrieve the stored setting value.

The control needs to be added into a section, which in turn needs to be added into a panel. Unless you’re building a theme from the ground up, panels and sections probably already exist, just add your control to an existing section. It’s not much, but I hope this helps.

Yes it is quite heavy for a newbie venturing into this area.
I will have to sit down and have a good old read.

Yes I already have a panel and section for the custom header that came with the theme, so I shouldn’t need to set that up? Just assign new controls in the functions.php file?
Does this automatically pull through into the preview window?

You have helped. So thank you. I feel like I’m going to have a lot of questions around this area :/

Ok, so I have managed to somehow add the three fields I wanted in the section I want.
I did this in customizer.php using the following code:

// header image custom title
  $wp_customize->add_setting(
    'custom_title',
      array (
        'default' => '',
        'transport'=>'postMessage',
      )
    );

  $wp_customize->add_control(
    new WP_Customize_Control(
      $wp_customize,
        'custom_title',
          array(
            'label' => __('Custom Header Title', 'my_aurelia_rose'),
            'section' => 'header_image',
            'settings' => 'custom_title',
            'type' => 'text',
          )
        )
      ); 
	
// header image custom description
  $wp_customize->add_setting(
    'custom_description',
      array (
        'default' => '',
        'transport'=>'postMessage',
      )
    );

  $wp_customize->add_control(
    new WP_Customize_Control(
      $wp_customize,
        'custom_description',
          array(
            'label' => __('Custom Header Description', 'my_aurelia_rose'),
            'section' => 'header_image',
            'settings' => 'custom_description',
            'type' => 'text',
          )
        )
      ); 
	
// header image custom link 
  $wp_customize->add_setting(
    'custom_link',
      array (
        'default' => 'https://mywebsite.com/blog',
        'transport'=>'postMessage',
      )
    );

  $wp_customize->add_control(
    new WP_Customize_Control(
      $wp_customize,
        'custom_link',
          array(
            'label' => __('Custom Header Link', 'my_aurelia_rose'),
            'section' => 'header_image',
            'settings' => 'custom_link',
            'type' => 'text',
          )
        )
      ); 

Now, my next task is to ensure that it comes through onto the Preview and then pulls through into the theme. This is now what I am struggling with.

Someone needs to write a clear and easy for beginners post or book on this. If there is one already, where?? ha.

• This reply was modified 7 years, 6 months ago by pixelboutiqueuk.

Any kind of progress is a good thing! Here’s a few more thoughts that should help some.

Using postMessage transport complicates things quite a bit, though it is a superior way to implement settings. I suggest staying with the default “refresh” transport for the time being. This way, if your theme is making use of the setting, it will appear in the preview automatically. With postMessage you need special jQuery code to selectively apply the settings through JS event binding. This is a good thing to implement at some point, but I advise focusing on the basics first.

You placed the code in customizer.php? I’m not sure what file that really is. Unless this is on a theme that’ll never be updated, that’s maybe not a good choice. Your code will be lost during updates. It appears you’ve done so because it affords access to $wp_customize, the customizer manager object. The same object can be accessed through the ‘customize_register’ action hook, where it is passed as a parameter to your callback. (see the first code example in my previous Customizer link) The action hook and callback can then be placed on functions.php of a child theme where it is safe from theme updates.

You can verify settings are correctly saved by examining the values in the options table through phpMyAdmin. phpMyAdmin is powerful software that can quickly destroy or corrupt your entire database. There’s no problem looking at values, do not attempt to change anything unless you are sure you know what you’re doing. Option settings are saved as individual options of course. Theme mods are saved as a serialized array under the option key name following this format: “theme_mods_{$theme_slug}”.

Getting your theme to use your settings is a matter of using get_option() or get_theme_mod() and using the returned value as is appropriate. Such code is often on modified templates saved in your child theme. Only when your settings appear, are saved, and used on your site correctly should you consider using postMessage transport. With postMessage you need additional jQuery code that uses the wp.customize() method to bind to the customizer setting, a callback that updates the appropriate page HTML with your passed setting value.

Once you’ve managed to figure all of this out, maybe you should write a nice tutorial on the topic ??

While I’m mostly kidding, a tutorial written for beginners by a beginner who had just figured it out for their self would be a valuable resource. When experts who know what they are doing try to write beginner tutorials, they are frequently a failure. From personal experience, writing a tutorial is a great way to learn about a topic in ways and in greater depth than you could have ever imagined had you merely learned for your own benefit. Naturally an expert should review your tutorial for technical accuracy, but a tutorial from a beginner’s perspective would be invaluable to others.

Thank you so much for this. I will sit and go through your response in detail tomorrow morning as that has all just gone straight over my head ha.

I agree, that most tutorials are way to wordy for beginners and have found it really hard to learn much from them at all.

I have seen a short course on treehouse for this topic in particular so I might give that a whirl.

Thanks again and I will report back with how I get on ??