元素API引物

开始

Element API允许开发人员通过创建自定义元素来扩展Pro和Cornerstone。本文将指导您完成创建元素的过程，同时还将分解元素的不同部分。

要继续学习，您可能需要下载本文中使用的代码。

下载样例元素插件

这是作为一个插件来设置的，但是也可以通过要求my-element.php文件中显然也．

你可以使用这个常量来启用应用开发工具:

定义('CS_APP_DEV_TOOLS'， true);

在使用构建器时，您现在应该在工具条的底部看到一个bug图标。在撰写本文时，它的唯一功能是显示当前检查的元素的值。

元素是通过定义创建的值，将它们连接到控制来允许用户自定义，然后使用渲染函数。所有这些都是通过元素完成的定义文件。让我们开始创建一个元素。

定义

下面的代码可以放在里面显然也子主题，或者在您的自定义插件(如样例元素下载)。

函数my_element_register() {require_once('./my- elelement .php');} add_action('cs_register_elements'， 'my_element_register')

这是我们的第一个版本my-element.php．

/ /注册“我的元素”cs_register_element (my-custom-element,数组(/ /定义的本地化的标题元素,以及它是如何标记元素库的标题 ' => __( ' 我的元素”、“your-text-domain) / /定义一些值,我们要让用户定制这个元素的值' = >阵列(' text_content ' = > cs_value(“,“标记”,真正的),/ /定义对照组,将出现在检查员导航栏“control_groups”= >阵列('我的元素 ' => __( ' 我的元素,'your-text-domain')， 'my-element:setup' => __(' setup'， 'your-text-domain')，)， //定义连接到值的控件。'controls' => array(array('key' => 'text_content'， 'type' => 'text-editor'， 'group' => 'my-element:setup'， 'label' => __('Content'， 'your-text-domain')，))， //连接一个用于渲染此元素的函数'render' => 'my_element_render'，));函数my_element_render($data) {extract($data);返回"
$text_content
";｝

这就是an元素定义．中的原生元素定义基石/包括/元素定义．请记住，他们中的许多人使用比上面的文件更高级的概念。本引物将从最简单形式的元素开始，然后添加几层以使其更强大。

试试吧!你会有一个工作元素。在构建器中添加它并检查元素后，您可以尝试更改内容，并在实时预览中看到它的更新。我知道，这里发生了很多事。让我们开始分析这段代码的含义以及它是如何工作的。

值

从上到下的工作标题是不言自明的，所以让我们直接进入值．

//定义一些我们想让用户为这个元素定制的值'values' => array('text_content' => cs_value('I am a custom element'， 'markup'， true))，

我们声明了一个名称为的值text_content当我们想在代码的其他部分引用这个值时，就会用到这个键。的函数签名cs_value

函数cs_value($default = null， $ designated = 'all'， $protected = false)

第一个参数(美元的违约)定义初始值。你可能已经意识到，当你注意到你的文本是预先填充“我是一个自定义元素”当你第一次加的时候。简单地跳过第三个参数(美元的保护)，我们可以用这个标记这个键为“Content”，用于保存和应用元素预设。当应用

使用第二个参数的正确值(美元指定)对于管理元素的实时预览性能很重要。它告诉渲染系统我们正在处理的值的类型。以下是主要的命名类型:

• 标记-当这个值发生变化时，它会向服务器发出一个HTTP请求，请求更新的属性，并为构建器预览获取新的标记。就性能而言，这是最昂贵的，但最通用的，因为它调用自定义PHP代码。
• attr-当这个值改变时，它会立即更新DOM中的值。
• 风格-我们稍后会讲到，但是我们的构建器允许你提供一个样式模板来输出生成的CSS。当具有此指定的值更改时，将导致重新计算生成的CSS。
• 所有-当这个值改变时，它会导致元素从服务器获取新的标记而且再次渲染生成的CSS。

关键是构建器足够聪明，可以在呈现元素时使用最少的资源。188bet网投使用风格(后面会讲到)和attr尽可能避免向服务器发送不必要的请求。我们试着加上anattr指定的值。更新你的my-element.php致以下:

//注册“我的元素”cs_register_element('My -custom- Element'， array(//定义元素的本地化标题以及它在元素库中的标记方式'title' => __('我的元素'，'your-text-domain')， //定义一些我们想让用户为该元素自定义的值'values' => array('text_content' => cs_value('我是一个自定义元素'，'markup'， true)， 'custom_attribute' => cs_value("， 'attr'， false))，//定义用于组织检查器'control_nav' =>数组中的控件的控件导航('My - Element' => __('My Element'， 'your-text-domain')， 'My - Element:setup' => __(' setup'， 'your-text-domain')， 'My - Element:design' => __(' design'， 'your-text-domain')，)， //定义连接到我们的值的控件。'controls' => array(array('key' => 'text_content'， 'type' => 'text-editor'， 'group' => 'my-element:setup'， 'label' => __('Content'， 'your-text-domain')，)， array('key' => 'custom_attribute'， 'type' => 'text'， 'group' => 'my-element:design'， 'label' => __('自定义属性'，'your-text-domain')，))， //连接一个用于渲染此元素的函数'render' => 'my_element_render'，);函数my_element_render($data) {extract($data);$atts = cs_atts(array('class' => 'my-element'， 'data-my-attribute' => $custom_attribute));返回“
$text_content
”;｝

以下是我们引入的变化:

• 增加了一个custom_attribute的值。attr指定
• 增加了一个新的控件和控件导航。我们将在下一节中更深入地探讨这些概念
• 更新渲染函数到输出data-my-attribute在div中存储的值custom_attribute

你还会注意到一个新函数:cs_atts．这只是一个助手方法，从数组返回HTML属性字符串，并应用正确的输出净化。

使用浏览器的开发人员工具检查DOM中的元素。看看data-my-attribute你现在爽了吗?开始输入我们连接到该值的文本输入。看看它是如何在没有任何HTTP请求到服务器的情况下实时更新的!

控制导航

在查看控件本身之前，让我们先了解一下control_nav以及它是如何用于组织的。以下是我们目前的情况:

“control_nav”= >阵列(“我的元素 ' => __( ' 我的元素”、“your-text-domain”)、“我的元素:设置 ' => __( ' 设置”、“your-text-domain”),“我的元素:设计 ' => __( ' 设计”、“your-text-domain”),),

这用于将控件组织成易于理解的部分。使用冒号描绘父组的子部分。这意味着“My Element”将是一个顶级组，其中有“Setup”和“Design”作为导航链接。我们的感言元素就是一个使用更多群组的好例子。

“control_nav”= >阵列(“证明”= >阵列(“标题 ' => __( ' 证明”、“__x __' ) ), ' 证明:内容' = >阵列(“标题 ' => __( ' ”、“__x内容 __' ) ), ' 证明:设置' = >阵列(标题 ' => __( ' ”、“__x设置 __' ) ), ' 证明:设计' = >阵列(“标题 ' => __( ' 设计”、“__x __' ) ), ' 证明:文本' = >阵列(“标题 ' => __( ' 文本”、“__x __' ) ), ' testimonial_cite ' = >阵列(“标题 ' => __( ' 引用”、“__x __' ) ), ' testimonial_cite:设置' = >阵列(标题 ' => __( ' 设置”,“__x __' ) ), ' testimonial_cite:设计' = >阵列(“标题 ' => __( ' 设计”、“__x __' ) ), ' testimonial_cite:文本' = >阵列(“标题 ' => __( ' 文本”、“__x __' ) ), ' testimonial_graphic ' = >阵列(“标题 ' => __( ' 图形”、“__x __' ) ), ' testimonial_graphic:设置' = >阵列(标题 ' => __( ' ”、“__x设置 __' ) ), ),

如果您尝试使用ential元素，您将看到代码如何与结果导航结构相关联。(你可能想知道“自定义”是怎么进来的。它来自一个“部分”，我们将在后面学习。)

对于更小的群体，我们使用:设置而且:设计按惯例作为子导航项。我们建议在适当的时候使用它，因为基石和专业用户已经熟悉它，但更欢迎您添加任何您想要的导航项。

请记住，如果导航项没有与之关联的控件，或者它的所有控件都被隐藏，则该导航项将被隐藏(请参阅控制条件)。

控制

如果你正在考虑如何将插件中的短代码集成为基石元素，那么你可能已经意识到这是多么强大。但说实话，这个元素还不是那么有趣。现在让我们讨论一下如何添加更多控件来为用户提供更强的自定义能力。

控制类型

控件类型显然比文本编辑器要多。让我们假设我们的custom_attribute是用户可以打开或关闭的东西。这意味着我们可以用a选择控制。更新类型你的控制选择并添加一个选项用一些数组选择包括开和关。

阵列('重要' = > ' custom_attribute ', '类型' = > '选择','团队' = > '我的元素:设计','标签 ' => __( ' 自定义属性”、“your-text-domain),选择' = >阵列('选择' = >阵列(阵列(“价值”= > false,”标签 ' => __( ' ”、“__x__”)),阵列(“价值”= > true,”标签 ' => __( ' ”、“__x __' ) ), ) ) )

我们还希望更新值，使其具有一个布尔缺省值，以匹配新控件

'custom_attribute' => cs_value(false， 'attr'， false)

现在如果你检查元素，你会看到选择控件，允许在打开和关闭之间切换。您可以使用浏览器的开发工具来观察它的来回切换。

对照组

与您之前看到的其他元素相比，您会注意到将两个控件放在单独的框中浪费了大量空间。默认情况下，每个顶级控件都有一个单独的“框”。当水平使用检查器时，这不是很有效。通过将两个控件合并为一个控件来解决这个问题集团控制。这是一种用于组织控件的特殊控件类型。

//定义连接到值的控件“控制”= >阵列(阵列(“类型”= >“集团”,“标签 ' => __( ' 设置”、“your-text-domain”),“集团' = > '我的元素:设置','控制' = >阵列(阵列(“关键”= >“text_content”,“类型”= >“文本编辑器”的标签 ' => __( ' 内容”、“your-text-domain”),),阵列('重要' = > ' custom_attribute ', '类型' = > '选择','标签 ' => __( ' 自定义属性”、“your-text-domain),选择' = >阵列('选择' = >阵列(阵列(“价值”= > false,”标签 ' => __( ' ”、“__x__”)),阵列(“价值”= >真的,'label' => __('On'， '__x__'))，)，)))))，

嵌套控件不需要指定它们属于哪个导航项，因为这是组的职责。并非所有控件类型(边境或链接例如)可以在组内使用，因为它们需要更多的空间。使用控件引用来确定哪些控件可以以这种方式使用。

控制条件

如果我们希望在自定义属性打开时出现另一个控件，该怎么办?让我们添加一个新控件，该控件使用条件．首先我们需要一个值:

'custom_attribute_content' => cs_value("， 'attr'， false)，

接下来，我们将添加一个文本控件。我们也会把它表示为一维空间。把这个放在现有的东西之后选择控制

array('key' => 'custom_attribute_content'， 'type' => 'text'， 'label' => __('自定义属性内容'，'your-text-domain')， 'options' => array('monospace' => true))

如果您对此进行测试，您将注意到切换On/Off没有任何作用。我们需要加上a条件由我们来控制。以下是更新后的代码:

array('key' => 'custom_attribute_content'， 'type' => 'text'， 'label' => __('Attribute Content'， 'your-text-domain')， 'condition' => array('custom_attribute' => true)， 'options' => array('monospace' => true))

现在，内容文本输入只在选择控件打开时显示。我们使用的是最简单的条件简写，即“如果的值custom_attribute是真正的”。该API支持检查多种条件并提供多种操作类型。了解更多链接

第一个样式控件

准备好做造型了吗?让我们添加一些值，我们将连接到一些样式控件。将以下行添加到您的值数组:

'background_color' => cs_value('transparent'， 'style'， false)， 'background_color_hover' => cs_value('transparent'， 'style'， false)， 'content_margin' => cs_value('0em'， 'style'， false)，

有些控件允许连接多个值。例如，一个颜色控件可以输出两种颜色。让我们用它来添加一个背景色。在您的末尾添加以下内容集团控件的控件列表(在选择为custom_attribute）.

数组(“钥匙”= >阵列(“颜色”= >“background_color”,“alt”= >“background_color_hover”,),'类型' = > '颜色',”标签 ' => __( ' 背景颜色”、“__x__”),“选项”= >阵列('标签 ' => __( ' 基地”、“__x__”),“alt_label ' => __( ' 交互”、“__x __' ), ) )

检查你的元素，你会看到两个颜色选择器并排。因为我们还没有生成CSS，所以现在是尝试开发工具的好时机。如果您启用了CS_APP_DEV_TOOLS常数，你可以点击“Bug”图标在工具条。您将看到覆盖预览区域并显示元素的值。调整颜色选择器，你可以看到输出的变化。

接下来我们将添加a保证金控件，我们将使用它来自定义主元素上的间距。控件的后面立即添加此控件，因此只能在顶层使用(不能在组中使用)集团控制。

array('key' => 'content_margin'， 'type' => 'margin'， 'label' => __('Content margin'， 'your-text-domain')， 'group' => 'my-element:design'，)

现在我们又回到了两个顶级盒子!

生成CSS

我们有一个独特的“生成CSS”系统，它采用样式模板(字符串)，并使用它为每个元素创建独特的样式。它经过优化，当相同类型的元素具有相同的值时，使用一个组合CSS选择器和一个属性声明。我们需要做的第一件事是更新渲染函数以输出元素的唯一类名。当它被传递时，它会自动为您提供元数据在钥匙下mod_id．下面是更新后的渲染函数:

函数my_element_render($data) {extract($data);$atts = cs_atts(array('class' => cs_attr_class($mod_id， 'my-element')， 'data-my-attribute' => $custom_attribute));返回“
$text_content
”;｝

的cs_attr_class函数接受无限的字符串参数，并将它们组合到一个类中。现在我们有了一个附加到元素的唯一类，我们可以用它来应用样式。在前端，类将是基于当前上下文(页面，标题等)的唯一标识，而在构建器中，它将是一个随机字符串。

要开始输出样式，我们需要向定义中添加一个样式模板。在传递给的数组中cs_register_element添加以下内容。把它放在渲染Callback是个好地方。

'style' => 'my_element_style'

这是函数本身，可以添加到你的my_element_render函数。

函数my_element_style() {ob_start();?> .$_el {background-color: $background_color;保证金:content_margin美元;} .$_el:hover {background-color: $background_color_hover;} < ?PHP返回ob_get_clean();｝

该函数需要返回一个字符串，因此为了可读性，我们使用了一些输出缓冲。您还可以将这些样式放在单独的文件中。这是示例元素下载的设置方法。例如:

函数my_element_style() {ob_start();包括“路径/ / my-element-css.php”;返回ob_get_clean ();｝

现在我们的模板正在加载，我们可以测试元素了。当你调整控件时，CSS会在实时预览中更新。有关如何编写这些模板的详细信息，请参见样式模板语法部分。

升级到生成器回调

在我们继续使用一些最强大的API特性(如Partials)之前，我们需要对我们的定义文件进行轻微的调整。这是最新的my-element.php包括到目前为止我们所做的所有更改以及生成器回调。

/ /注册“我的元素”cs_register_element (my-custom-element,数组(/ /定义的本地化的标题元素,以及它是如何标记元素库的标题 ' => __( ' 我的元素”、“your-text-domain) / /定义一些值,我们要让用户定制这个元素的值' = >阵列(' text_content ' = > cs_value(“我是定制元素”,“标记”,真的),“custom_attribute”= > cs_value(假,attr,假),“custom_attribute_content”= > cs_value(“‘attr,假),'content_margin' => cs_value("， 'style'， false)， 'background_color' => cs_value('transparent'， 'style'， false)， 'background_color_hover' => cs_value('transparent'， 'style'， false)，)， // 'builder' => 'my_element_builder_setup'， //连接样式模板回调'style' => 'my_element_style'， //连接一个用于渲染此元素的函数'render' => 'my_element_render'，);//生成器设置函数my_element_builder_setup(){返回数组(//定义将出现在检查器导航栏中的控件组'control_nav' => array('My - Element' => __('My Element'， 'your-text-domain')， 'My - Element: Setup' => __('Setup'， 'your-text-domain')， 'My - Element:design' => __(' design'， 'your-text-domain')，)， //定义连接到我们的值的控件。'controls' =>数组(//设置数组('type' => 'group'， 'label' => __('Setup'， 'your-text-domain')， 'group' => 'my-element: Setup'， 'controls' =>数组(//设置:内容数组('key' => 'text_content'， 'type' => 'text-editor'， 'label' => __('Content'， 'your-text-domain')，)， //设置:自定义属性数组(“关键”= >“custom_attribute”,'类型' = > '选择',”标签 ' => __( ' 自定义属性”、“your-text-domain),选择' = >阵列('选择' = >阵列(阵列(“价值”= > false,”标签 ' => __( ' ”、“__x__”)),阵列(“价值”= > true,”标签 ' => __( ' ”、“__x __' ) ), ), ) ), // 设置:属性数组内容(“关键”= >“custom_attribute_content”,“类型”= >“文本”,”标签 ' => __( ' 属性内容”、“your-text-domain”),“条件”= >数组(“custom_attribute”= > true),“选项”= >数组(“等宽字体”= > true)),阵列(“钥匙”= >数组(“颜色”= >“background_color”、“alt”= >“background_color_hover”),“类型”= >“颜色”的标签 ' => __( ' 背景颜色”、“__x__”),“选项”= >阵列('标签 ' => __( ' 基地”、“__x__”),“alt_label ' => __( ' 互动”、“__x__”),))))， // Content Margin array('key' => 'content_margin'， 'type' => ' Margin'， 'label' => __('Content Margin'， 'your-text-domain')， 'group' => 'my-element:design'，)));} //样式模板函数my_element_style() {ob_start();?> .$_el {background-color: $background_color;保证金:content_margin美元; } .$_el:hover { background-color: $background_color_hover; }  cs_attr_class( $mod_id, 'my-element' ), 'data-my-attribute' => $custom_attribute ) ); return "
$text_content
"; }

我们所做的就是把我们的代码定义拆分成几个部分。这一行告诉构建器调用my_element_builder_callback函数。

'my_element_builder_callback' => '

从回调返回的数组将用新值更新元素定义。我们这么做的原因是构建器回调不在前端运行．为了提高性能，我们应该避免运行任何对前端不重要的代码。累积的本机库表示数千个控件，如果在每次前端页面加载时都定义这些控件，这将意味着相当大的内存使用量。

这一调整也为我们提供了一些仅适用于构建器的API特性抽象技术当然还有偏音。

分音

这是您真正开始了解如何利用API的地方。如果您想从我们的原生按钮元素开始，并添加一些额外的控件，该怎么办?或者，如果你想复制我们的一个模式元素，但提供你自己的内容呢?偏微分就是解决方法。

添加自定义部分

对于我们的第一个例子，我们将学习如何添加那些“自定义”控件。我们称它为偏导，因为它几乎都在原始元素的末尾。记住，元素需要值和控件的组合。我们将从定义开始值我们所需要的。更新定义值看起来像这样:

'values' => cs_compose_values(array('text_content' => cs_value('我是一个自定义元素'，'markup'， true)， 'custom_attribute' => cs_value(false， 'attr'， false)， 'custom_attribute_content' => cs_value("， 'attr'， false)， 'content_margin' => cs_value("， 'style'， false)， 'background_color' => cs_value('transparent'， 'style'， false)， 'background_color_hover' => cs_value('transparent'， 'style'， false)，)， 'omega')，

的cs_compose_values函数接受无限个参数。如果您传递一个数组，这些值将通过。如果传递一个字符串，它将定位该键的预定义值。如果你看一看包括/元素/ values.php基石您可以看到所有可用的预定义值。总结一下ω，我们将定义下面的值，这些值也将有与之关联的控件。

• id—文本输入，用于指定元素ID
• 类-文本输入添加自定义类
• css- CSS元素代码编辑器
• hide_bp-根据当前断点选择要隐藏的控件。类根据此值自动在幕后更新。

我们还希望以类似的方式组合控件。将构建器回调更新为如下所示(为简洁起见，省略了实际控件)。

函数my_element_builder_setup(){返回cs_compose_controls(array('control_nav' => array(/*…*/)， 'controls' =>数组(/*…*/))， cs_partial_controls('omega'));｝

的cs_partial_controls函数返回包含控制而且control_nav．然后cs_compose_controls将它们组合成一个输出。为了在前端工作，我们需要更新渲染函数来使用这些新值。我们只需要添加ID属性和更新class属性。元素CSS和断点可见性在幕后自动处理。

函数my_element_render($data) {extract($data);$atts = cs_atts(array('id' => $id， 'class' => cs_attr_class($mod_id， 'my-element'， $class)， 'data-my-attribute' => $custom_attribute));返回“
$text_content
”;｝

背景

您可能想要使用的另一个常见部分是高级背景。与Omega一样，我们需要更新我们的值、控件和呈现函数。为了简洁起见，本节中的代码示例部分被缩短了。不要删除任何现有的值或控件。

首先，我们要更新我们的值。简单的添加bg到名单上去。

'values' => cs_compose_values(数组(/*…*/)， 'bg'， ' ω ')，

下面是我们需要添加的部分控件。注意，我留下了一个注释掉的条件行。有些部分像bg支持隐藏/显示所有控件的条件。我们在原生元素中使用它来允许用户打开或关闭高级背景。

函数my_element_builder_setup(){返回cs_compose_controls(array('control_nav' => array(/*…*/)， 'controls' =>数组(/*…*/))， cs_partial_controls('bg'， array('group' => 'my-element:design'， // 'condition' => array('custom_attribute' => true)，))， cs_partial_controls('omega'));｝

最后，让我们在渲染函数中得到这个输出。

函数my_element_render($data) {extract($data);$atts = cs_atts(array('id' => $id， 'class' => cs_attr_class($mod_id， 'my-element'， $class)， 'data-my-attribute' => $custom_attribute));ob_start ();?> 
 > < ?PHP echo cs_get_partial_view('bg'， cs_extract($data, array('bg' => ")));? > < div > < ?PHP echo $text_content;?>
 

.$_el{位置:相对;background - color: background_color美元;保证金:content_margin美元;｝

cs_register_element('My -custom-element'， array(//定义元素的本地化标题以及它在元素库中的标记方式'title' => __('My element'， 'your-text-domain')， 'icon' => ''…

函数my_element_builder_setup(){返回cs_compose_controls(array('control_nav' => array(/*…*/)， 'controls' =>数组(/*…*/)， 'controls_std_content' => array(/*…* /),“controls_std_design_setup”= >阵列(/ *……* /),“controls_std_design_colors”= >阵列(/ *……*/)，)， cs_partial_controls('bg'， array('group' => 'my-element:design'))， cs_partial_controls('omega'));｝

函数my_element_builder_setup(){返回cs_compose_controls(array('control_nav' => array(/*…*/)， 'controls' =>数组(/*…*/)， 'controls_std_content' => array(/*…* /),“controls_std_design_setup”= >阵列(/ *……* /),“controls_std_design_colors”= >阵列(/ *……* /)), cs_partial_controls(“bg”,数组(“集团”= >“我的元素:设计”)),阵列('控制' = >阵列(/ *……*/)，)， cs_partial_controls('omega'));｝

'options' => array('choices' => cs_recall('options_choices_off_on_bool'))

//在定义被注册之前cs_remember('my_options'， array(/* anything */));//生成器函数内的任何位置。$my_options = cs_remember('my_options');

cs_control('margin'， 'content'， array('label_prefix' => __('content'， 'your-text-domain')， 'group' => 'my-element:design'，))