{"id":15731859,"url":"https://github.com/ndm2/ckeditor-placeholder-elements","last_synced_at":"2025-05-13T03:45:04.599Z","repository":{"id":15513409,"uuid":"18247664","full_name":"ndm2/ckeditor-placeholder-elements","owner":"ndm2","description":"A CKEditor plugin that adds support for predefined placeholder elements.","archived":false,"fork":false,"pushed_at":"2024-04-24T15:56:51.000Z","size":60,"stargazers_count":7,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-09T18:54:10.274Z","etag":null,"topics":["ckeditor","ckeditor-plugin","placeholder"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ndm2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-03-29T18:25:20.000Z","updated_at":"2022-05-10T11:14:17.000Z","dependencies_parsed_at":"2024-04-05T14:50:15.839Z","dependency_job_id":"ec7f1168-3312-453a-8686-c52c46a04d64","html_url":"https://github.com/ndm2/ckeditor-placeholder-elements","commit_stats":{"total_commits":50,"total_committers":3,"mean_commits":"16.666666666666668","dds":0.54,"last_synced_commit":"9b64af3302cc7de7806715f3b7c1cf8360c8c8df"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndm2%2Fckeditor-placeholder-elements","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndm2%2Fckeditor-placeholder-elements/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndm2%2Fckeditor-placeholder-elements/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndm2%2Fckeditor-placeholder-elements/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ndm2","download_url":"https://codeload.github.com/ndm2/ckeditor-placeholder-elements/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253870823,"owners_count":21976610,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ckeditor","ckeditor-plugin","placeholder"],"created_at":"2024-10-04T00:06:30.002Z","updated_at":"2025-05-13T03:45:04.577Z","avatar_url":"https://github.com/ndm2.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CKEditor Placeholder Elements Plugin\n\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.txt)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/ndm2/ckeditor-placeholder-elements/ci.yml?branch=master\u0026style=flat-square)](https://github.com/ndm2/ckeditor-placeholder-elements/actions/workflows/ci.yml?query=branch%3Amaster)\n\nThis is a [CKEditor](http://ckeditor.com/) plugin that adds support for predefined placeholder elements.\n\n\n## What's it good for?\n\nWell, in case you want the user to be able to use placeholders from a predefined collection, there you go...\nactually it's pretty much for my own specific use, but if it fits your needs, have fun with it.\n\n\n## Requirements\n\nThis plugins requires CKEditor 4.3+ and the following plugins:\n\n* [Rich Combo](http://ckeditor.com/addon/richcombo)\n* [Widget](http://ckeditor.com/addon/widget)\n\n\n## How to use?\n\n### Installation\n\nYou can either\n\n* use [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (and copy the files into\n  `ckeditor/plugins/placeholder_elements/`)\n  ```bash\n  $ npm i @ndm2/ckeditor-placeholder-elements\n  ```\n\n* [Bower](http://bower.io)\n  ```bash\n  $ bower install ndm2-ckeditor-placeholder-elements\n  ```\n\n* clone or download and unpack the repository into `ckeditor/plugins/placeholder_elements/`\n  ```bash\n  $ git clone --depth=1 https://github.com/ndm2/ckeditor-placeholder-elements ./ckeditor/plugins/placeholder_elements/\n  ```\n\n* or use [Composer](https://getcomposer.org) (optionally in combination with a custom directory installer like for\nexample [mnsami/composer-installer-plugin](https://github.com/mnsami/composer-installer-plugin))\n  ```bash\n  $ composer require ndm2/ckeditor-placeholder-elements\n  ```\n\nIf you can't install the plugin directly in the CKEditor plugin folder, use\n[`CKEDITOR.plugins.addExternal()`](http://docs.ckeditor.com/#!/api/CKEDITOR.resourceManager-method-addExternal) to\npoint the editor to the directory where you've placed the plugin.\n\n\n### Configuration\n\nInclude the name of the plugin in the ckeditor `extraPlugins` option:\n\n```js\nconfig.extraPlugins = 'placeholder_elements';\n```\n\nBy default the UI element is appended to the [`insert` toolbar](http://docs.ckeditor.com/#!/guide/dev_toolbar).\nIn case you want to [place it manually](http://docs.ckeditor.com/#!/guide/dev_toolbar-section-%22item-by-item%22-configuration),\nuse `PlaceholderElements` as the identifier.\n\nThe following options are available for configuration:\n\n```js\nconfig.placeholder_elements = {\n\t// The CSS applied to the placeholder elements.\n\tcss:\n\t\t'.cke_placeholder_element { background: #ffff00; }' +\n\t\t'a .cke_placeholder_element { text-decoration: underline }',\n\n\t// Defines whether the placeholders should be draggable.\n\tdraggable: false,\n\n\t/**\n\t * A list of placeholders, defined as objects with `label` and `value`\n\t * properties, where the label is being displayed in the menu, and value\n\t * is used as the placeholder text.\n\t *\n\t * Note that delimiters are added automatically, so the value should be\n\t * defined without!\n\t *\n\t * [\n\t *     {label: 'Placeholder 1', value: 'PLACEHOLDER_1'},\n\t *     {label: 'Placeholder 2', value: 'PLACEHOLDER_2'},\n\t *     {label: 'Placeholder 3', value: 'PLACEHOLDER_3'},\n\t *     // ...\n\t * ]\n\t *\n\t * When using the `combo` UI type, it's also possible to define groups\n\t * using the `group` and `placeholders` keys, where `group` defines the\n\t * title of group that is displayed in the menu, and `placeholders` is an\n\t * array that holds the groups placeholders.\n\t *\n\t * Note that grouping is only a visual thing, placeholder values must still\n\t * be unique!\n\t *\n\t * [\n\t *     {\n\t *         group: 'Group 1',\n\t *         placeholders: [\n\t *             {label: 'Placeholder 1', value: 'PLACEHOLDER_1'},\n\t *             {label: 'Placeholder 2', value: 'PLACEHOLDER_2'}\n\t *         ]\n\t *     },\n\t *     {\n\t *         group: 'Group 2',\n\t *         placeholders: [\n\t *             {label: 'Placeholder 3', value: 'PLACEHOLDER_4'},\n\t *             {label: 'Placeholder 4', value: 'PLACEHOLDER_5'}\n\t *         ]\n\t *     },\n\t *     // ...\n\t * ]\n\t */\n\tplaceholders: [],\n\n\t// Defines the delimiter that indicates the start of a placeholder\n\tstartDelimiter: '{',\n\n\t// Defines the delimiter that indicates the end of a placeholder\n\tendDelimiter: '}',\n\n\t/**\n\t * Defines the type of UI element that holds the placeholders. Either\n\t * `button` or `combo`.\n\t */\n\tuiType: 'button'\n};\n```\n\n\n### Modifying the list of placeholders at runtime\n\nThe available placeholders can be modified at runtime using the instance of the `PlaceholdersCollection` class\nassociated with the corresponding plugin instance.\n\nChanges made to this collection are automatically being applied to the editor UI and content.\n\n```js\nvar editorIdentifier = 'editor1'; // in most cases this is the ID or\n                                  // name of the DOM element replaced\n                                  // by the editor\nvar editor = CKEDITOR.instances[editorIdentifier];\nvar plugin = editor.plugins.placeholder_elements.instances[editor.id];\n\n/** @type {PlaceholdersCollection} */\nvar placeholders = plugin.placeholders;\n```\n\nAdd a new placeholder\n```js\nvar placeholder = {label: 'Foo', value: 'FOO'};\nplaceholders.add(placeholder);\n```\n\nAdd a new placeholder to an existing group (or append a new group in case it doesn't exist yet)\n```js\nvar placeholder = {label: 'Foo', value: 'FOO', group: 'Bar'};\nplaceholders.addToGroup(placeholder);\n```\n\nRemove the third placeholder\n```js\nplaceholders.removeAt(2);\n```\n\nModify an existing placeholder\n```js\nvar placeholder = placeholders.getAt(2);\nplaceholder.label = 'New Label';\nplaceholders.replaceAt(2, placeholder);\n```\n\nFor more check out the [`PlaceholdersCollection` class](https://github.com/ndm2/ckeditor-placeholder-elements/blob/master/plugin.js)\nsource.\n\n**Note** that applying multiple consecutive changes can lead to flickering, due to the nature of `change` events causing\nUI and content updates. Make use of the `PlaceholdersCollection.batchChanges()` method to avoid this, changes made from\nthe callback passed to this method will cause only a single `change` event to be fired afterwards.\n\n```js\nplaceholders.batchChanges(function()\n{\n\tthis.replaceAt(2, {label: 'Foo', value: 'FOO'});\n\tthis.add({label: 'Bar', value: 'BAR'});\n});\n```\n\n\n## Issues\n\nPlease use the [issue tracker](https://github.com/ndm2/ckeditor-placeholder-elements/issues) to report problems.\n\n\n## License\n\nLicensed under [The MIT License](http://www.opensource.org/licenses/mit-license.php).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndm2%2Fckeditor-placeholder-elements","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fndm2%2Fckeditor-placeholder-elements","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndm2%2Fckeditor-placeholder-elements/lists"}