ndm2 / ckeditor-placeholder-elements
A CKEditor plugin that adds support for predefined placeholder elements.
Installs: 590
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 3
Forks: 4
Open Issues: 0
Language:JavaScript
This package is auto-updated.
Last update: 2024-10-24 17:00:38 UTC
README
This is a CKEditor plugin that adds support for predefined placeholder elements.
What's it good for?
Well, in case you want the user to be able to use placeholders from a predefined collection, there you go... actually it's pretty much for my own specific use, but if it fits your needs, have fun with it.
Requirements
This plugins requires CKEditor 4.3+ and the following plugins:
How to use?
Installation
You can either
-
use npm (and copy the files into
ckeditor/plugins/placeholder_elements/
)$ npm i @ndm2/ckeditor-placeholder-elements
-
$ bower install ndm2-ckeditor-placeholder-elements
-
clone or download and unpack the repository into
ckeditor/plugins/placeholder_elements/
$ git clone --depth=1 https://github.com/ndm2/ckeditor-placeholder-elements ./ckeditor/plugins/placeholder_elements/
-
or use Composer (optionally in combination with a custom directory installer like for example mnsami/composer-installer-plugin)
$ composer require ndm2/ckeditor-placeholder-elements
If you can't install the plugin directly in the CKEditor plugin folder, use
CKEDITOR.plugins.addExternal()
to
point the editor to the directory where you've placed the plugin.
Configuration
Include the name of the plugin in the ckeditor extraPlugins
option:
config.extraPlugins = 'placeholder_elements';
By default the UI element is appended to the insert
toolbar.
In case you want to place it manually,
use PlaceholderElements
as the identifier.
The following options are available for configuration:
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' };
Modifying the list of placeholders at runtime
The available placeholders can be modified at runtime using the instance of the PlaceholdersCollection
class
associated with the corresponding plugin instance.
Changes made to this collection are automatically being applied to the editor UI and content.
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;
Add a new placeholder
var placeholder = {label: 'Foo', value: 'FOO'}; placeholders.add(placeholder);
Add a new placeholder to an existing group (or append a new group in case it doesn't exist yet)
var placeholder = {label: 'Foo', value: 'FOO', group: 'Bar'}; placeholders.addToGroup(placeholder);
Remove the third placeholder
placeholders.removeAt(2);
Modify an existing placeholder
var placeholder = placeholders.getAt(2); placeholder.label = 'New Label'; placeholders.replaceAt(2, placeholder);
For more check out the PlaceholdersCollection
class
source.
Note that applying multiple consecutive changes can lead to flickering, due to the nature of change
events causing
UI and content updates. Make use of the PlaceholdersCollection.batchChanges()
method to avoid this, changes made from
the callback passed to this method will cause only a single change
event to be fired afterwards.
placeholders.batchChanges(function() { this.replaceAt(2, {label: 'Foo', value: 'FOO'}); this.add({label: 'Bar', value: 'BAR'}); });
Issues
Please use the issue tracker to report problems.
License
Licensed under The MIT License.