It seems my curse is to work on branching projects and so today’s struggle was to field a decent brand new Theme Customizer control.
The base
Any control willing to populate the Theme Customizer must extend the WP_Customize_Control class.
That class extension must be made at customize_register hook time.
For major and well more detailed info see Otto on WordPress article.
What I’m trying to do
To complement the realization of a two-sided (theme user and theme developer sides) of an Headway Themes block I need theme user to be able to upload and select multiple images.
Default WordPress Theme Customizer blocks will not allow me to do that and looking around the web of connected computers did not help.
Long story short: I’ve set to build one “from scratch” and try to learn something along the way.
Getting into the customizer
I’m using my ThemeCustomizeSection helper class to hook into the Theme Customizer and load my custom control class; in my main plugin class the __construct function contains the lines
...
// will add the 'background_images' section
$this->themeSection = new ThemeCustomizeSection('Background images', 'Set one or more images to be used as the site background.', __NAMESPACE__);
// tell the helper to use this custom control class too
$this->themeSection->addCustomControl('multi-image', '\tad\customizer\controls\MultiImageControl');
// add the setting and the control with it
// will be stored in 'background_images[image_sources]' as an option
$this->themeSection->addSetting('image_sources', 'Upload or select one or more images.', '', 'multi-image');
...
where the custom control class to use, MultiImageControl reads like
<?php
namespace tad\customizer\controls;
if (!class_exists('\WP_Customize_Control')) {
return null;
}
class MultiImageControl extends \WP_Customize_Control
{
public $type = 'multi-image';
public function render_content()
{
// render the title
$this->theTitle();
}
protected function theTitle()
{
?>
<label>
<span class="customize-control-title">
<?php echo esc_html($this->label); ?>
</span>
</label>
<?php
}
}
and will humbly appear in the Theme Customizer bringing no real function to it [caption id=“attachment_754” align=“aligncenter” width=“996”]
Unuseful control[/caption]
Adding a button to upload images and remove them
I will be using the Media uploader to allow theme user to upload images and will extend the MultiImageControl class to actually show something
<?php
namespace tad\customizer\controls;
if (!class_exists('\WP_Customize_Image_Control')) {
return null;
}
class MultiImageControl extends \WP_Customize_Image_Control
{
public $type = 'multi-image';
public function enqueue()
{
wp_enqueue_media();
// enqueue the script
// enqueue the style
}
public function render_content()
{
// get the set values if any
$imageSrcs = $this->value();
if (is_null($imageSrcs)) {
$imageSrcs = array();
}
// render the title
$this->theTitle();
$this->theButtons();
$this->theUploadedImages($imageSrcs);
}
protected function theTitle()
{
?>
<label>
<span class="customize-control-title">
<?php echo esc_html($this->label); ?>
</span>
</label>
<?php
}
public function theButtons()
{
?>
<div>
<a href="#" class="button-secondary multi-images-upload">
<?php echo 'Upload'; ?>
</a>
<a href="#" class="button-secondary multi-images-upload">
<?php echo 'Remove images'; ?>
</a>
</div>
<?php
}
public function theUploadedImages($srcs = array())
{
?>
<div class="uploaded-images">
<?php if (is_array($srcs)): ?>
<?php foreach ($srcs as $src): ?>
<img src="<?php echo $src; ?>" />
<?php endforeach ?>
<?php endif ?>
</div>
<?php
}
}
and will produce the following result in the Customizer screen [caption id=“attachment_755” align=“aligncenter” width=“996”]
Seemingly useful control[/caption]
Next step
I will bind the Media Uploader to the Upload button and will bind another action to remove all images to the other button.