README

这是一个支持预定义占位符元素的 CKEditor 插件。

它有什么好处？

如果您想让用户能够使用预定义集合中的占位符，那就这么做吧... 实际上它主要是为了我的特定用途，但如果它符合您的需求，您就可以尽情享受它了。

要求

此插件需要 CKEditor 4.3+ 以及以下插件

• Rich Combo
• Widget

如何使用？

安装

您可以选择以下任一方式

• 使用 npm （并将文件复制到 ckeditor/plugins/placeholder_elements/）

  $ npm i @ndm2/ckeditor-placeholder-elements

• Bower

  $ bower install ndm2-ckeditor-placeholder-elements

• 克隆或下载并解压缩存储库到 ckeditor/plugins/placeholder_elements/

  $ git clone --depth=1 https://github.com/ndm2/ckeditor-placeholder-elements ./ckeditor/plugins/placeholder_elements/

• 或使用 Composer （可选地与自定义目录安装程序结合使用，例如 mnsami/composer-installer-plugin）

  $ composer require ndm2/ckeditor-placeholder-elements

如果您无法直接在 CKEditor 插件文件夹中安装插件，请使用 CKEDITOR.plugins.addExternal() 将编辑器指向您放置插件的位置。

配置

在 ckeditor 的 extraPlugins 选项中包含插件名称

config.extraPlugins = 'placeholder_elements';

默认情况下，UI 元素附加到 insert 工具栏。如果您想 手动放置，请使用 PlaceholderElements 作为标识符。

以下选项可用于配置

config.placeholder_elements = {
	// The CSS applied to the placeholder elements.
	css:
		'.cke_placeholder_element { background: #ffff00; }' +
		'a .cke_placeholder_element { text-decoration: underline }',

	// Defines whether the placeholders should be draggable.
	draggable: false,

	/**
	 * A list of placeholders, defined as objects with `label` and `value`
	 * properties, where the label is being displayed in the menu, and value
	 * is used as the placeholder text.
	 *
	 * Note that delimiters are added automatically, so the value should be
	 * defined without!
	 *
	 * [
	 *     {label: 'Placeholder 1', value: 'PLACEHOLDER_1'},
	 *     {label: 'Placeholder 2', value: 'PLACEHOLDER_2'},
	 *     {label: 'Placeholder 3', value: 'PLACEHOLDER_3'},
	 *     // ...
	 * ]
	 *
	 * When using the `combo` UI type, it's also possible to define groups
	 * using the `group` and `placeholders` keys, where `group` defines the
	 * title of group that is displayed in the menu, and `placeholders` is an
	 * array that holds the groups placeholders.
	 *
	 * Note that grouping is only a visual thing, placeholder values must still
	 * be unique!
	 *
	 * [
	 *     {
	 *         group: 'Group 1',
	 *         placeholders: [
	 *             {label: 'Placeholder 1', value: 'PLACEHOLDER_1'},
	 *             {label: 'Placeholder 2', value: 'PLACEHOLDER_2'}
	 *         ]
	 *     },
	 *     {
	 *         group: 'Group 2',
	 *         placeholders: [
	 *             {label: 'Placeholder 3', value: 'PLACEHOLDER_4'},
	 *             {label: 'Placeholder 4', value: 'PLACEHOLDER_5'}
	 *         ]
	 *     },
	 *     // ...
	 * ]
	 */
	placeholders: [],

	// Defines the delimiter that indicates the start of a placeholder
	startDelimiter: '{',

	// Defines the delimiter that indicates the end of a placeholder
	endDelimiter: '}',

	/**
	 * Defines the type of UI element that holds the placeholders. Either
	 * `button` or `combo`.
	 */
	uiType: 'button'
};

在运行时修改占位符列表

可以使用与相应插件实例关联的 PlaceholdersCollection 类实例在运行时修改可用的占位符。

对集合所做的更改将自动应用到编辑器 UI 和内容。

var editorIdentifier = 'editor1'; // in most cases this is the ID or
                                  // name of the DOM element replaced
                                  // by the editor
var editor = CKEDITOR.instances[editorIdentifier];
var plugin = editor.plugins.placeholder_elements.instances[editor.id];

/** @type {PlaceholdersCollection} */
var placeholders = plugin.placeholders;

添加新的占位符

var placeholder = {label: 'Foo', value: 'FOO'};
placeholders.add(placeholder);

将新的占位符添加到现有组（或者如果尚不存在，则附加新组）

var placeholder = {label: 'Foo', value: 'FOO', group: 'Bar'};
placeholders.addToGroup(placeholder);

删除第三个占位符

placeholders.removeAt(2);

修改现有的占位符

var placeholder = placeholders.getAt(2);
placeholder.label = 'New Label';
placeholders.replaceAt(2, placeholder);

有关更多信息，请查看 PlaceholdersCollection 类 的源代码。

注意 由于 change 事件引起 UI 和内容更新的性质，连续应用多个更改可能导致闪烁。请使用 PlaceholdersCollection.batchChanges() 方法来避免这种情况，此方法传递给回调的更改将仅在之后引发单个 change 事件。

placeholders.batchChanges(function()
{
	this.replaceAt(2, {label: 'Foo', value: 'FOO'});
	this.add({label: 'Bar', value: 'BAR'});
});

问题

请使用 问题跟踪器 报告问题。

许可

许可协议为 MIT 许可协议。