In the previous post about a Backstretch based Headway block plugin I’ve outlined theme user options and how those will be taken into account from a theme designer using the block settings supplied by the block/plugin developer; that role distinction is important and it’s, in my opinion, one of the main benefits of Headway.
I will be using my libraries to keep the code concise but those will always expose things with a pretty ablative name so comprehension should not be an issue.
The file structure and organization comes straight from a grunt Headway block template.
Setting up the theme user options
The theme user will be given the option to set one or more images as the body background or to, upon a theme developer decision, set a body background color.
Those controls will be added in the Main class of the block plugin adding a section to the Theme Customizer the same way any plugin would do
<?php
namespace htbackstretch;
use \tad\wrappers\ThemeCustomizeSection as Section;
use \tad\wrapers\headway\BlockSetting as Setting;
class Main
{
protected $section;
protected $blockSetting;
public function __construct()
{
add_action('after_setup_theme', array($this, 'blockRegister'));
add_action('init', array($this, 'extend_updater'));
// add the 'Background images' section
// options will be stored in the 'backstretch' option in an array format
// the namespace is used as the text domain
$this->themeSection = new Section('Background images', 'backstretch', 'What to use as site background?', __NAMESPACE__);
// add the multi-image control to allow the user to select one or more images
// defaults to no images
// will be stored in 'backstretch[imageSources]' option
$this->themeSection->addSetting('imageSources', 'Upload or select one or more images.', '', 'multi-image');
// load site-wide settings from the database
// using namespace as it's the same as the block id
$blockSettings = new \tad\wrappers\HeadwayBlockSetting(__NAMESPACE__);
// if no setting about the color picker is found or
// theme developer so did allow then show the color picker
// value will be stored in 'backstretch[bg-color]' option
$showColorPicker = $blockSettings->settings['bg-color-allow'];
if (is_null($showColorPicker) or (bool)$showColorPicker) {
$this->themeSection->addSetting('bg-color', 'Select a background color', '#FFF', 'color');
}
}
public function blockRegister()
{
if (!class_exists('Headway')) {
return;
}
return headway_register_block('\htbackstretch\Block', plugins_url(false, __FILE__));
}
}
Which, in turn, will show the controls in the theme customizer upon activation [caption id=“attachment_824” align=“aligncenter” width=“858”]
Theme user options[/caption]
Implementing theme developer settings
It’s now time to add settings the theme developer can use to control what shows up in the theme customizer and how to use what the user did chose.
The settings will all apply to the entire theme and will hence be shown in a theme-wide setting panel.
To add the panel I will hook into the htbackstretch\Main::__construct method
public function __construct()
{
// same code as before here
// register this block theme-wide options
add_action('after_setup_theme', array($this, 'addVisualEditorPanels'));
}
to delegate the addVisualEditorPanel method with the heavy lifting
public function addVisualEditorPanels()
{
// include the class defining those options
include_once dirname(__FILE__) . '/VisualEditorPanel.php';
// register the visual editor panel
$class = '\htbackstretch\VisualEditorPanel';
$tag = 'headway_visual_editor_display_init';
// hook in with a priority higher than the one Headway registers
// its own setup block to have the Header Image options panel show
// on the right side of it
$priority = 1000;
add_action($tag, create_function('', 'return headway_register_visual_editor_panel_callback(\'' . $class . '\');'), $priority);
}
The VisualEditorPanel class is an endless stream of options like
<?php
namespace htbackstretch;
class VisualEditorPanel extends \HeadwayVisualEditorPanelAPI
{
public $id = 'htbackstretch';
public $name = 'Backstretch';
public $mode = 'grid';
public $tabs = array(
'user-options' => 'User Options',
);
public $inputs = array(
'user-options' => array(
'heading-no-image' => array(
'type' => 'heading',
'name' => 'heading-no-image',
'label' => 'No image selected'
),
'htbackstretch-no-image-selected' => array(
'type' => 'select',
'name' => 'htbackstretch-no-image-selected',
'label' => 'If the user did not select any image:',
'options' => array(
'user can set a background color',
'use a default color',
'use a default image'
),
'toggle' => array(
0 => array(
'hide' => array(
'#input-htbackstretch-default-bg-color',
'#input-htbackstretch-default-bg-image'
)
),
1 => array(
'show' => array(
'#input-htbackstretch-default-bg-color'
),
'hide' => array(
'#input-htbackstretch-default-bg-image'
)
),
2 => array(
'hide' => array(
'#input-htbackstretch-default-bg-color'
),
'show' => array(
'#input-htbackstretch-default-bg-image'
)
)
)
),
...
and so on until an interface like the one below is shown to the theme developer [caption id=“attachment_825” align=“aligncenter” width=“1024”]
Theme developer settings 1[/caption] [caption id=“attachment_826” align=“aligncenter” width=“1024”]
Theme developer settings 2[/caption]
Next steps
Now that the theme developer can take decisions on user options it’s time to actually use those settings in the block code.
Complete article code is on GitHub.