A plugin for CKEditor 5 that provides an extendable autocomplete functionality with predefined mention and HTML replacement logic.
Partially based on the code and idea of the CKEditor 5 mention feature.
This package was created by the ckeditor5-package-generator package.
See docs: docs (webpage coming soon)
See extended example usage: sample (dll.html and ckeditor.ts for a custom ckeditor build)
To add the autocomplete feature to your editor, install the @znuny/ckeditor5-autocomplete-plugin package:
npm install --save @znuny/ckeditor5-autocomplete-pluginThen add the Autocomplete plugin to your plugin list and configure it:
import { Autocomplete } from '@znuny/ckeditor5-autocomplete-plugin';
ClassicEditor
.create( document.querySelector( '#editor' ), {
// Load the plugin.
plugins: [ Autocomplete, /* ... */ ],
// Configure the plugin.
autocomplete: {
combineResultOfCompletionGroupsWithSameMarker: true,
// add more plugin configurations here
// ...
completionGroups: [
{
// use mention like completions
completions: [
{
name: "max",
content: "@max",
dataAttributes: [
{
name: "user-id",
value: "123max123"
},
{
name: "my-custom-data",
value: "foobert"
}
]
},
{
name: "Marry Ann",
content: "@Marry Ann with slightly longer content"
}
],
matchingMarker: "@",
completionMatchingHandler: "nameStartsWith",
offerCompletionOptionsWithMarkerMatchingOnly: true
},
{
// use non-mention, content replacement like completions
completions: [
{
name: "mytext",
content: "my custom text replacement",
useAsHTMLReplacement: true
},
{
name: "a more complex html input of CKEditor generated source code",
content: '<p><span style="color:green;">here is <i>some</i> text</span><br><span style="color:orange;">.. and some more - <s>wow</s></span></p><p><br>cool, <strong>even line break works</strong> as well as inline code blocks: <code><?php echo 1; ?></code></p>',
useAsHTMLReplacement: true
}
],
matchingMarker: "##",
completionMatchingHandler: "nameStartsWith",
offerCompletionOptionsWithMarkerMatchingOnly: false
},
// add more completion group definitions
// ...
]
}
} )
.then( /* ... */ )
.catch( /* ... */ );- General plugin configuration options
- Completion group configuration options
- Completion element configuration options
To read about the CKEditor 5 framework, visit the CKEditor5 documentation.
Creating commits will enforce matching the predefined code style by a "pre-commit" hook executed script.
Npm scripts are a convenient way to provide commands in a project. They are defined in the package.json file and shared with other people contributing to the project. It ensures that developers use the same command with the same options (flags).
All the scripts can be executed by running npm run <script>. Pre and post commands with matching names will be run for those as well.
The following scripts are available in the package.
Starts a HTTP server with the live-reload mechanism that allows previewing and testing plugins available in the package.
When the server has been started, the default browser will open the developer sample. This can be disabled by passing the --no-open option to that command.
You can also define the language that will translate the created editor by specifying the --language [LANG] option. It defaults to 'en'.
Examples:
# Starts the server and open the browser.
npm run start
# Disable auto-opening the browser.
npm run start -- --no-open
# Create the editor with the interface in German.
npm run start -- --language=deAllows executing unit tests for the package, specified in the tests/ directory. The command accepts the following modifiers:
-
--coverage– to create the code coverage report, -
--watch– to observe the source files (the command does not end after executing tests), -
--source-map– to generate source maps of sources, -
--verbose– to print additional webpack logs.
Examples:
# Execute tests.
npm run test
# Generate code coverage report after each change in the sources.
npm run test -- --coverage --testRuns ESLint, which analyzes the code (all *.ts files) to quickly find problems.
Examples:
# Execute eslint.
npm run lintSimilar to the lint task, stylelint analyzes the CSS code (*.css files) in the package.
Examples:
# Execute stylelint.
npm run stylelintCreates a DLL-compatible package build which can be loaded into an editor using DLL builds.
Examples:
# Build the DLL file that is ready to publish.
npm run dll:build
# Build the DLL file and listen to changes in its sources.
npm run dll:build -- --watchCreates a simple HTTP server (without the live-reload mechanism) that allows verifying whether the DLL build of the package is compatible with the CKEditor 5 DLL builds.
Examples:
# Starts the HTTP server and opens the browser.
npm run dll:serveCollects translation messages (arguments of the t() function) and context files, then validates whether the provided values do not interfere with the values specified in the @ckeditor/ckeditor5-core package.
The task may end with an error if one of the following conditions is met:
- Found the
Unused contexterror – entries specified in thelang/contexts.jsonfile are not used in source files. They should be removed. - Found the
Context is duplicated for the iderror – some of the entries are duplicated. Consider removing them from thelang/contexts.jsonfile, or rewrite them. - Found the
Context for the message id is missingerror – entries specified in source files are not described in thelang/contexts.jsonfile. They should be added.
Examples:
npm run translations:collectDownload translations from the Transifex server. Depending on users' activity in the project, it creates translations files used for building the editor.
The task requires passing the URL to Transifex API. Usually, it matches the following format: https://www.transifex.com/api/2/project/[PROJECT_SLUG].
To avoid passing the --transifex option every time when calls the command, you can store it in package.json, next to the ckeditor5-package-tools translations:download command.
Examples:
npm run translations:download -- --transifex [API URL]Uploads translation messages onto the Transifex server. It allows for the creation of translations into other languages by users using the Transifex platform.
The task requires passing the URL to the Transifex API. Usually, it matches the following format: https://www.transifex.com/api/2/project/[PROJECT_SLUG].
To avoid passing the --transifex option every time when you call the command, you can store it in package.json, next to the ckeditor5-package-tools translations:upload command.
Examples:
npm run translations:upload -- --transifex [API URL]This project (as well as the @znuny/ckeditor5-autocomplete-plugin package) is distributed under the GNU General Public License (GPL v3) - see the accompanying LICENSE file for general license information. If you need more details you can have a look here.