公开配置选项

插件可以选择公开平台在管理界面中显示的配置选项。

何时应公开配置选项？

在开发基于配置值（例如，全局选项或身份验证详细信息）的插件时，您可以实现可配置的插件，以便通过管理界面轻松公开这些选项。

创建可配置的插件

要向现有插件添加配置选项，插件必须实现 IConfigurablePlugin 接口。IConfigurablePlugin 接口在 Limyee.Components.dll 的 Limyee.Extensibility.Version1 命名空间中定义。IConfigurablePlugin 接口有两个成员：要公开的配置选项由 ConfigurationOptions 属性标识，当前配置数据将提供给 Update 方法。配置选项是使用 Dynamic Configuration 定义的，它是与小组件共享实现，可以基于元数据自动生成表单。示例如下：

using Limyee.DynamicConfiguration.Components;
using Limyee.Extensibility.Version1;

namespace Samples
{
	public class SampleConfigurablePlugin : IConfigurablePlugin
	{
		private IPluginConfiguration _configuration;

		#region IPlugin
		public string Name => "可配置插件示例";
		public string Description => "";
		public void Initialize() { }
		#endregion

		#region IConfigurablePlugin
		public PropertyGroup[] ConfigurationOptions
		{
			get
			{
				var group = new PropertyGroup("options", "选项", 0);

				var stringProperty = new Property("stringProperty", "字符串属性示例", PropertyType.String, 0, "这是默认值")
				{
					DescriptionText = "字符串属性描述示例"
				};
				group.Properties.Add(stringProperty);

				var selectableProperty = new Property("selectableProperty", "可选属性示例", PropertyType.String, 1, "One")
				{
					DescriptionText = "可选属性描述示例"
				};
				selectableProperty.SelectableValues.Add(new PropertyValue("One", "选择一", 1));
				selectableProperty.SelectableValues.Add(new PropertyValue("Two", "选择二", 2));
				selectableProperty.SelectableValues.Add(new PropertyValue("Three", "选择三", 3));
				selectableProperty.SelectableValues.Add(new PropertyValue("Four", "选择四", 4));
				group.Properties.Add(selectableProperty);

				return new[] { group };
			}
		}

        public void Update(IPluginConfiguration configuration)
		{
			_configuration = configuration;
		}
		#endregion
	}
}

在此示例中，将两个属性添加到配置选项定义名为“选项”的组中。第一个属性称为“字符串属性示例”，表示一个字符串值。第二个属性“可选属性示例”也是一个字符串值，但它定义了可选选项，这些选项将此字段显示为下拉列表。在管理界面中部署和查看此插件时，它将显示为：

Update 方法根据 ConfigurationOptions 定义的元数据接收插件的配置数据。然后，该插件可以读取和使用此配置数据，来适合实现其行为。IPluginConfiguration 的 Update 方法提供了包括获取和设置插件配置值的方法。例如，要读取示例定义的第一个字符串属性的当前值，插件将调用：

var stringValue = _configuration.GetString("stringProperty");

定义配置元数据时，将使用 Limyee.DynamicConfiguration.DynamicConfiguration.dll 中 Limyee.DynamicConfiguration.Components 命名空间中的项。这些包括：

• PropertyGroup：表示 Limyee 电商平台管理界面中的选项卡。
• PropertySubGroup：表示管理界面中组字段的子分组。
• Property。属性存在于组或子分组中，并用名称和描述表示单个值。该平台将使用默认界面实现自动显示所有属性（类型“Custom”除外）。通过将 ControlType 属性设置为实现 IPropertyControl 的类，可以自定义属性值编辑器。下面列出了平台中的可用属性控件。
• PropertyValue。属性值存在于属性中，用于为属性定义的可选选项。默认情况下，在属性上定义一个或多个属性值将导致该属性显示为下拉列表。
• PropertyRule。可以在属性上定义规则，通过引用规则实现（即实现 IPropertyRule 接口的类）来自动执行值约束。

可用的属性控件

当使用动态配置属性实例定义配置元数据时，Limyee 电商平台将为除自定义之外的每种数据类型显示默认编辑器。若要自定义值编辑器的显示，可以将属性的 ControlType 属性设置为实现 IPropertyControl 的类的类型。Limyee 电商平台包括一些可由插件和小组件使用的属性控件：

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

需要配置才能启用插件

通常，插件要运行必需将配置值填上。在这些情况下，在充分指定配置之前不允许插件运行是很重要的。此方案是通过实现 Limyee.Components.dll 中定义的 IRequiredConfigurationPlugin 接口来实现的。此接口添加了一个属性 IsConfigured，平台读取该属性以确定插件在允许主动启用之前是否配置了该插件。如果启用了插件，但配置不令人满意，则该插件将在管理界面中以红色突出显示，并且不会主动启用（即不会完全初始化，因此将无法与平台交互）。基于前面的可配置插件示例的实现如下：

using Limyee.DynamicConfiguration.Components;
using Limyee.Extensibility.Version1;

namespace Samples
{
	public class SampleConfigurablePlugin : IConfigurablePlugin, IRequiredConfigurationPlugin
	{
		private IPluginConfiguration _configuration;

		#region IPlugin
		public string Name => "可配置插件示例";
		public string Description => "";
		public void Initialize() { }
		#endregion

		#region IConfigurablePlugin
		public PropertyGroup[] ConfigurationOptions
		{
			get
			{
				var group = new PropertyGroup("options", "选项", 0);

				var stringProperty = new Property("stringProperty", "字符串属性示例", PropertyType.String, 0, "这是默认值")
				{
					DescriptionText = "字符串属性描述示例"
				};
				group.Properties.Add(stringProperty);

				var selectableProperty = new Property("selectableProperty", "可选属性示例", PropertyType.String, 1, "One")
				{
					DescriptionText = "可选属性描述示例"
				};
				selectableProperty.SelectableValues.Add(new PropertyValue("One", "选择一", 1));
				selectableProperty.SelectableValues.Add(new PropertyValue("Two", "选择二", 2));
				selectableProperty.SelectableValues.Add(new PropertyValue("Three", "选择三", 3));
				selectableProperty.SelectableValues.Add(new PropertyValue("Four", "选择四", 4));
				group.Properties.Add(selectableProperty);

				return new[] { group };
			}
		}

        public void Update(IPluginConfiguration configuration)
		{
			_configuration = configuration;
		}
		#endregion

		#region IRequiredConfigurationPlugin
		public bool IsConfigured
		{
			get { return _configuration.GetString("stringProperty") == "有效"; }
		}
		#endregion
	}
}

在此示例实现中，仅当“stringProperty”配置字段的值为“有效”时，才接受配置。当插件已启用且值不为“有效”时，该插件将在列表中以红色背景显示：

当它具有有效值时，它将正常列出（并完全启用/初始化）：

自定义配置界面的显示

虽然 Limyee 电商平台将实现了 IConfigurablePlugin 的插件公开其配置选项和自动生成配置表单，并处理将自定义属性控件用于单个字段的情况，但有时整个配置界面需要使用自定义布局和实现。为了能够完全覆盖配置界面，插件可以从 Limyee.Components.dll 的 Limyee.Extensibility.Version1 命名空间实现 IRenderableConfigurablePlugin 接口。此接口添加了一个方法 GetConfigurationHtml，该方法需要一个可以插入到插件编辑界面中的 HTML 结果。例如

using Limyee.DynamicConfiguration.Components;
using Limyee.Extensibility.Version1;

namespace Samples
{
	public class SampleConfigurablePlugin : IConfigurablePlugin, IRequiredConfigurationPlugin, IRenderableConfigurablePlugin
	{
		private IPluginConfiguration _configuration;

		#region IPlugin
		public string Name => "可配置插件示例";
		public string Description => "";
		public void Initialize() { }
		#endregion

		#region IConfigurablePlugin
		public PropertyGroup[] ConfigurationOptions
		{
			get
			{
				var group = new PropertyGroup("options", "选项", 0);

				var stringProperty = new Property("stringProperty", "字符串属性示例", PropertyType.String, 0, "这是默认值")
				{
					DescriptionText = "字符串属性描述示例"
				};
				group.Properties.Add(stringProperty);

				var selectableProperty = new Property("selectableProperty", "可选属性示例", PropertyType.String, 1, "One")
				{
					DescriptionText = "可选属性描述示例"
				};
				selectableProperty.SelectableValues.Add(new PropertyValue("One", "选择一", 1));
				selectableProperty.SelectableValues.Add(new PropertyValue("Two", "选择二", 2));
				selectableProperty.SelectableValues.Add(new PropertyValue("Three", "选择三", 3));
				selectableProperty.SelectableValues.Add(new PropertyValue("Four", "选择四", 4));
				group.Properties.Add(selectableProperty);

				return new[] { group };
			}
		}

        public void Update(IPluginConfiguration configuration)
		{
			_configuration = configuration;
		}
		#endregion

		#region IRequiredConfigurationPlugin
		public bool IsConfigured
		{
			get { return _configuration.GetString("stringProperty") == "有效"; }
		}
		#endregion

		#region IRenderableConfigurable
		public string GetConfigurationHtml(string apiJson)
		{
			return string.Format(@"
<div id=""sample-configurable-plugin-editor"">
	这是个<strong>自定义</strong>的配置界面。
</div>
<script type=""text/javascript"">
	(function() {{
		var api = {0};
		api.registerContent([{{
			name: '示例',
			orderNumber: 0,
			selected: function() {{ $('#sample-configurable-plugin').show(); }},
			unselected: function() {{ $('#sample-configurable-plugin').hide(); }}
		}}]);
	}})();
</script>
",
	apiJson);
		}
		#endregion
	}
}

此示例实现是只读的，但显示为：

GetConfigurationHtml 方法提供了 JSON 格式的客户端 API，可用于与平台定义的插件编辑器界面交互和扩展。该示例注册一个名为“示例”的选项卡，但可以添加多个选项卡。

此示例不是实际示例，因为它实际上不会公开或编辑任何配置字段。通常，完整实现将使用插件定义的小组件，该小组件可以读/写插件配置值，通过将 JSON API 传递到私有小组件 API 来实现 GetConfigurationHtml。