小组件配置

动态配置是一种基于元数据能动态生成表单的格式，小组件可用来定义配置选项。

何时使用动态配置？

当开发人员希望向管理员和其他非开发人员公开小组件的配置选项时，动态配置是必要的。动态配置小组件工作室上的小组件中被定义为 XML。

XML 配置定义

[
 <propertyGroup>
   [
   <property>
     [<propertyValue />]*
     [<propertyRule />]*
   </property>
   ]*
 </propertyGroup>
 ]*

一个或多个属性组可以包含一个或多个属性。每个组都表示为小组件配置窗口的选项卡，每个属性存储一个值。每个属性都可以选择定义可选值和规则。

可以使用 $limyee_v1_widget 扩展上的 get 和 set 方法为小组件检索属性值。

<propertyGroup />

<propertyGroup [id=""] [resourceName="" [resourceFile=""]] [text=""] [descriptionResourceName="" [descriptionResourceFile=""]] [descriptionText=""] [orderNumber=""] [visible=""] [other attributes]>...</propertyGroup>

定义配置属性组。在小组件配置窗口中，每个组都由一个选项卡表示。

属性：

• id 是组的标识符。
• resourceName 是标识此组名称的语言资源名称。
• resouceFile 是标识资源 resourceName 的语言资源文件的文件名。
• text 是此组的纯文本名称。
• descriptionResourceName 是标识此组描述的语言资源名称。
• descriptionResourceFile 是标识资源 descriptionResourceName 的语言资源文件的文件名。
• descriptionText 是此组的纯文本描述。
• orderNumber 是此组的整数序号（默认情况下，组的顺序与 XML 配置定义的顺序相同）。
• visible 是一个布尔值（true 或 false），用于标识此组是否应显示在小组件配置窗口中（默认情况下，显示所有组）。
• [other attributes] 是属性规则或属性控件用于其他配置的其他属性。

资源名称或文本是必需的。

<property />

<property id="" dataType="" [resourceName="" [resourceFile=""]] [text=""] [descriptionResourceName="" [descriptionResourceFile=""]] [descriptionText=""] [orderNumber=""] [defaultValue=""] [editable=""] [visible=""] [controlType=""] [scope=""] [other attributes] />

定义配置组中的配置属性。

属性：

• id 是此属性的标识符。这是通过小组件的 $limyee_v1_widget 扩展方法检索值时使用的标识符。
• 数据类型是此属性的数据类型。可能的值包括：
  • Bool 存储 true 或 false 值，默认情况下呈现为复选框。
  • Color 存储 HTML 颜色值，默认情况下呈现为颜色选择器。
  • Date 存储日期，默认情况下呈现为带有日历选择器的日期样式文本框。
  • DateTime 存储日期和时间，默认情况下呈现为带有日历选择器的日期/时间样式文本框。
  • Double 存储双精度浮点值，默认情况下呈现为带有双精度浮点验证的文本框。
  • Guid 存储全局唯一标识符值，默认情况下呈现为带有 GUID 验证的文本框。
  • Html 存储 HTML 值，默认情况下呈现为富文本框。
  • Int 存储一个整数值，默认情况下呈现为带有整数验证的文本框。
  • String 存储字符串值，默认情况下呈现为文本框。
  • Time 存储时间，默认情况下呈现为带有时间选择器的时间样式文本框。
  • Unit 存储 CSS 单位，默认情况下呈现为单位样式文本框。
  • Url 存储 URL，默认情况下呈现为带有 URL 验证的文本框。
  • Custom 存储可与自定义属性控件一起实现使用的自定义字符串值。
• resourceName 是标识此属性名称的语言资源的名称。
• resouceFile 是标识资源 resourceName 的语言资源文件的文件名。
• text 是此属性的纯文本名称。
• descriptionResourceName 是标识此属性的描述的语言资源的名称。
• descriptionResourceFile 是标识资源 descriptionResourceName 的语言资源文件的文件名。
• descriptionText 是此属性的纯文本描述。
• orderNumber 是此属性的整数序号（默认情况下，属性按在 XML 配置中定义的顺序排列）。
• defaultValue 是此属性的默认值。
• editable 是一个布尔值（true 或 false），用于标识此属性在小组件配置窗口中是否可编辑（默认情况下，所有属性都是可编辑的）。
• visible 是一个布尔值（true 或 false），用于标识此属性是否显示在小组件配置窗口中（默认情况下，将显示所有属性）。
• controlType 是实现 Limyee.DynamicConfiguration.Components.IPropertyControl 的完整 .net 类型名称（Namespace.ClassName，AssemblyName），用于编辑此属性。
• scope 定义了应在其中存储此属性值的非标准范围。通常，属性的值与小组件的单个实例相关联，但是，在定义范围时，该值将应用于定义范围内小组件的所有实例。可能的值包括：
  • site 与此小组件在整个站点中的所有实例共享此属性值。
  • group 当前群组上下文中此小组件的所有实例共享此属性的值。
  • store 与当前商店上下文中此小组件的所有实例共享此属性的值。
  • blog 与当前博客上下文中此小组件的所有实例共享此属性的值。
    当用户没有适当的权限在属性定义的范围内编辑主题时，该属性将不会显示在小组件的配置表单中。
• [other attributes] 是属性规则或属性控件用于其他配置的其他属性。

除了 id 和 dataType 之外，还需要 resourceName 或 text。

<propertyValue />

<propertyValue value="" [resourceName="" [resourceFile=""]] [text=""] [orderNumber=""] [other attributes] />

定义属性的可选值。为属性定义可选值时，默认情况下，将使用下拉列表呈现该属性。

属性：

• value 是可选值，选择时应将关联的属性设置为该值。
• resourceName 是标识此可选值的名称的语言资源的名称。
• resouceFile 是标识资源 resourceName 的语言资源文件的文件名。
• text 是此可选值的纯文本名称。
• orderNumber 是此可选值的整数序号（默认情况下，可选值按在 XML 配置中定义的顺序排列）。
• [other attributes] 是属性规则或属性控件用于其他配置的其他属性。

除了 value 外，还需要 resourceName 或 text 。

<propertyRule />

<propertyRule type="" [other attributes]/>

定义要应用于属性的规则。

属性：

• type 是实现 Limyee.DynamicConfiguration.Components.IPropertyRule 的完整 .net 类型名称（Namespace.ClassName，AssemblyName），用于应用于关联的属性。
• [other attributes] 是用于配置属性规则的其他属性。

作用域属性

有时，将小组件放置在多个页面上共享单个配置可能很有用。例如，“群组应用程序导航”小组件在群组内多个页面显示时，应始终显示同一群组导航选项卡。小组件开发人员可以通过为一个或多个小组件配置属性定义显式范围来启用此行为。

定义属性的作用域

属性的作用域由属性 scope 定义。通常，属性的值与小组件的单个实例相关联，但是，在定义范围时，该值将小组件应用于定义范围内的所有实例。

例如，在下面的示例中，widgetHeader 属性使用默认范围（小组件实例），导航属性定义群组的显式范围。

<propertyGroup id="options" resourceName="Options">
    <property id="widgetHeader" resourceName="Widget_Title" dataType="string" defaultValue="${resource:Groups_GroupApplicationNavigation_Name}" controlType="Limyee.Controls.ContentWidgetTokenStringControl, Limyee.Controls" />
    <property id="navigation" dataType="custom" controlType="Limyee.Controls.CustomNavigationCustomControl, Limyee.Controls" maximumDepth="1" resourceName="Groups_GroupApplicationNavigation_Navigation" descriptionResourceName="Groups_GroupApplicationNavigation_Navigation_Description" navigationType="group" scope="group" />
</propertyGroup>

支持的范围

默认范围是小组件的实例。如果未定义作用域属性，则使用此作用域。显式定义范围时，支持以下值：

• site 与此小组件在整个站点中的所有实例共享此属性值。
• group 当前群组上下文中此小组件的所有实例共享此属性的值。
• store 与当前商店上下文中此小组件的所有实例共享此属性的值。
• blog 与当前博客上下文中此小组件的所有实例共享此属性的值。
  当用户没有适当的权限在属性定义的范围内编辑主题时，该属性将不会显示在小组件的配置表单中。

平台属性控件类型

动态配置定义了一个默认用户界面，用于编辑每个受支持的属性数据类型，但是，在某些情况下，更具体的用户界面会很有帮助。动态配置通过在声明定义 controlType 来支持备用的编辑体验。该平台支持以下备用属性控件类型：

• 博客选择自定义控件
• 复选框列表字符串控件
• 自定义导航自定义控件
• 电子邮件字符串控件
• 论坛选择自定义控件
• 论坛可排序列表控件
• 群组或应用程序选择自定义控件
• 群组选择自定义控件
• 媒体库选择自定义控件
• 属性可见性选择控件
• 富文本编辑器 HTML 控件
• 可排序列表自定义控件
• 标记化字符串控件
• 用户文件 URL 控件
• 用户资料字段选择自定义控件
• 用户资料组选择自定义控件
• 百科选择自定义控件