WordPress 4.1还增加了对JavaScript较重和/或高量控制完全使用JavaScript的支持。这允许更具动态的行为,尤其是与动态增添控制的控件有关的行为。目前,核心颜色和媒体控件当前利用此API,所有核心控件最终将来都将在将来使用它。基于PHP的控制API不会消失,但是将来大多数控件都可能使用新的API,因为它为用户和开发人员提供了更快的体验。引入了JS-Template部分和面板的类似API WordPress 4.3;但是,如WordPress 4.7时,JS中动态创建对象的易用性还有一些差距,请参阅 #30741。
注册的控制类型
为了引入一个具有同一类型的多个自定义器控件的模板的概念,我们需要引入一种使用Customize Manager注册一种控制类型的方法。以前,只有使用自定义控件添加自定义控制对象WP_Customize_Manager::add_control()
。但是,如果未加载该类型的其他实例,则将添加的控制类型检测到每种类型的一个模板渲染一个模板不允许动态创建新的控件。WP_Customize_Manager::register_control_type() solves this:
add_action( 'customize_register', 'prefix_customize_register' );
function prefix_customize_register( $wp_customize ) {
// Define a custom control class, WP_Customize_Custom_Control.
// Register the class so that its JS template is available in the Customizer.
$wp_customize->register_control_type( 'WP_Customize_Custom_Control' );
}
所有注册的控制类型都将其模板打印到定制器中WP_Customize_Manager::print_control_templates()
。
将PHP控制数据发送到JavaScript
虽然定制器控制数据始终传递给控制JS模型,并且始终可以扩展,但是在使用JS模板时,您更有可能需要将数据发送下来。任何您都希望访问的任何东西render_content()
在控制模板中,需要将PHP导出到JavaScript才能访问。WP_Customize_Control
默认情况下导出以下控制类变量:
type
label
description
active
(布尔州)
您可以通过覆盖来添加特定于自定义控件的其他参数WP_Customize_Control::to_json()
在您的自定义控制子类中。在大多数情况下,您需要打电话给父班’to_json()
方法还可以确保所有核心变量也被导出。这是核心颜色控制的示例:
public function to_json() {
parent::to_json();
$this->json['statuses'] = $this->statuses;
$this->json['defaultValue'] = $this->setting->default;
}
JS/下划线模板
将自定义控制类注册为控制类型并导出任何自定义类变量后,您可以创建将渲染控制UI的模板。您将覆盖WP_Customize_Control::content_template()
(默认为空)作为替代WP_Customize_Control::render_content()
。渲染内容仍然是调用的,因此请确保在子类中还用空功能覆盖它。
下划线风格的自定义控制模板与PHP非常相似。随着越来越多的WordPress核心成为JavaScript驱动的,这些模板变得越来越普遍。核心中的一些示例模板代码可以在 媒体,修订,这 主题浏览器,乃至 在二十五个主题中,其中使用JS模板来保存配色方案数据并立即预览“定制器”中的配色方案。了解这些模板如何在核心中研究类似代码的最佳方法,因此,这是一个简短的例子:
class WP_Customize_Color_Control extends WP_Customize_Control {
public $type = 'color';
// ...
/**
* Render a JS template for the content of the color picker control.
*/
public function content_template() {
?>
<# var defaultValue = '';
if ( data.defaultValue ) {
if ( '#' !== data.defaultValue.substring( 0, 1 ) ) {
defaultValue = '#' + data.defaultValue;
} else {
defaultValue = data.defaultValue;
}
defaultValue = ' data-default-color=' + defaultValue; // Quotes added automatically.
} #>
<label>
<# if ( data.label ) { #>
<span class="customize-control-title">{{{ data.label }}}</span>
<# } #>
<# if ( data.description ) { #>
<span class="description customize-control-description">{{{ data.description }}}</span>
<# } #>
<div class="customize-control-content">
<input class="color-picker-hex" type="text" maxlength="7" placeholder="<?php esc_attr_e( 'Hex Value' ); ?>" {{ defaultValue }} />
</div>
</label>
<?php
}
}
在上面的核心自定义颜色控制的模板中,您可以看到,在关闭PHP标签后,我们有一个JS模板。符号围绕要评估的语句使用 – 在大多数情况下,这用于条件。我们导出到JS的所有控制实例数据都存储在“数据”对象中,我们可以使用double(Escaped)或Triple(UneScaped)Brace表示法打印一个变量
{{ }}
。正如我之前所说,掌握这样的写作控件的最佳方法是阅读现有示例。 WP_Customize_Upload_Control
最近 更新以利用此API 同样,将媒体管理器的实现方式很好地集成在一起,并从最少的代码中挤压了大量功能。如果您想要一些非常好的练习,请尝试将其他一些核心控件转换为使用此API,并将补丁提交给核心!
把碎片放在一起
这是在自定义定制器控制子类中利用新API所需的摘要:
- 做你的render_content()函数为空(但确实需要存在覆盖默认值的功能)。
- 创建一个新功能,content_template(),放置旧内容render_content()那里。
- 通过修改将控件导出到JavaScript所需的任何自定义类变量,通过修改浏览器(JSON数据)中的JavaScriptto_json()函数(请参阅wp_customize_color_control例如)。
- 转换PHP从render_content()使用JS模板,使用围绕JS语句进行评估和{{}}周围要打印的变量。PHP类变量在数据对象中可用;例如,可以打印标签{{data.label}}。
- 注册自定义控制类/类型。此关键步骤告诉定制器为此控件打印模板。这与仅针对所有添加的控件的打印模板不同,因为这些想法是从一个模板中呈现此控制类型的许多实例,并且将来任何注册的控制类型都可以用于动态控制 – 创建。只是做类似的事情$ wp_customize-> register_control_type(' wp_customize_color_control');。
自定义API的只有PHP的部分仍然得到完全支持,并且可以使用完美。但是,给出了长期目标,可以使定制器更灵活地进行操作,例如在没有pageload的情况下在定制器中切换主题,因此强烈鼓励使用JS/下划线模板为所有可行的自定义定制对象使用JS/下划线模板。