CKEditor 5 Autocomplete Plugin

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)

Table of contents

• CKEditor 5 Autocomplete Plugin
  • Table of contents
  • Quick start
  • Configuration options
  • Developing the package
    • Update dependencies like the ckeditor5 framework
  • Available scripts
    • start
    • test
    • lint
    • stylelint
    • build:dist
    • translations:collect
    • translations:download
    • translations:upload
  • License

Quick start

To add the autocomplete feature to your editor, install the @znuny/ckeditor5-autocomplete-plugin package:

npm install --save @znuny/ckeditor5-autocomplete-plugin

Then 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>&lt;?php echo 1; ?&gt;</code></p>',
                            useAsHTMLReplacement: true
                        }
                    ],
                    matchingMarker: "##",
                    completionMatchingHandler: "nameStartsWith",
                    offerCompletionOptionsWithMarkerMatchingOnly: false
                },
                // add more completion group definitions
                // ...
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Configuration options

• General plugin configuration options
• Completion group configuration options
• Completion element configuration options

Developing the package

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.

Update dependencies like the ckeditor5 framework

1. Checkout the latest project version (pull main + maybe a new version branch) and run npm run start. Validate in the browser that the current build is working. Just try to autocomplete something. There shouldn't be any errors or warnings in the JS console.
2. Run npm run build:dist and backup the old build version, to check later for build changes: cp dist/index.js.map /tmp/index.js.map_old
3. Validate currently used ckeditor5 version: npm list --depth=0 ckeditor5. It should match with our latest project latest release notes, like 47.1.0.
4. Check latest ckeditor5 version we are going to update to later: npm info ckeditor5. It should display something like latest: 47.6.1, that's the relevant part.
5. Check the update guides (like for needed migrations) https://ckeditor.com/docs/ckeditor5/latest/updating/guides/update-to-47.html, also for minor version updates!
   • When jumping over a major version, you'll need to check all the guides between in the correct order.
6. Update the dependencies using npm update and, if necessary, make the changes to the project code required for the update.
7. Validate usage of the expected, new ckeditor5 dependency version: npm list --depth=0 ckeditor5
8. Build and check the new version: npm run build:dist
   • If diff dist/index.js.map /tmp/index.js.map_old does not show any changes, you can skip building a new project release (and the further steps).
   • Run npm run start and open the browser to validate the current build is working (may force reload resources to ensure using the latest version). Just try to autocomplete something. There shouldn't be any errors or warnings in the JS console.
9. If everything seems fine, create a commit with a message like update dependencies to get ckeditor5 v47.6.1, containing at least the changed package-lock.json.
   • Push it into the remote repo and wait to see if the CI succeeds.
10. Prepare the new version release
    • Update project version in package.json like from 0.0.13 to 0.0.14
    • Run npm update again to get our new package version into package-lock.json
    • Do the commit like git commit -am "set version 0.0.14; update docs" (docs will be updated using a commit hook, wait for it)
    • You may note the documentation in docs/ has automatically being updated. Check the changes and amend it to our commit: git add docs; git commit --amend
      • There may be some warnings like Failed to resolve link to ..., I think it's fine to ignore them for now.
    • After that no staged or unstaged changes should be left in the local repo.
11. Push the current state into the remote repo and wait to see if the CI succeeds.
12. Optional: when using a custom release brauch, open mr and merge into main if everything is fine. Pull the local project repo and procees with the latest changes in the main branch.
13. Create a tag locally git tag 0.0.14 and push it to make the CI build and publish the new release: git push origin main --tags

Available scripts

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.

start

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=de

test

Allows 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:

# Optional: custom chrome binary path export; will automatically get one if not set
export CHROME_BIN=/usr/bin/chromium

# Execute tests.
npm run test

# Generate code coverage report after each change in the sources.
npm run test -- --coverage --test

# Execute specific test file.
npm run test -- tests/autocomplete-ui.ts

lint

Runs ESLint, which analyzes the code (all *.ts files) to quickly find problems.

Examples:

# Execute eslint.
npm run lint

stylelint

Similar to the lint task, stylelint analyzes the CSS code (*.css files) in the package.

Examples:

# Execute stylelint.
npm run stylelint

build:dist

Creates npm and browser builds of your plugin. These builds can be added to the editor by following the Configuring CKEditor 5 features guide.

Examples:

# Builds the `npm` and browser files thats are ready to publish.
npm run build:dist

translations:collect

Collects 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 context error – entries specified in the lang/contexts.json file are not used in source files. They should be removed.
• Found the Context is duplicated for the id error – some of the entries are duplicated. Consider removing them from the lang/contexts.json file, or rewrite them.
• Found the Context for the message id is missing error – entries specified in source files are not described in the lang/contexts.json file. They should be added.

Examples:

npm run translations:collect

translations:download

Download 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]

translations:upload

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]

License

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.