|
|
@@ -0,0 +1,534 @@
|
|
|
+---
|
|
|
+menu-title: Vue.js component
|
|
|
+category: builds-integration-frameworks
|
|
|
+order: 40
|
|
|
+---
|
|
|
+
|
|
|
+# Rich text editor component for Vue.js
|
|
|
+
|
|
|
+[](https://www.npmjs.com/package/@ckeditor/ckeditor5-vue)
|
|
|
+
|
|
|
+The [easiest way](#quick-start) to use CKEditor 5 in your Vue.js application is by choosing one of the {@link builds/guides/overview#available-builds rich text editor builds} and simply passing it to the configuration of the Vue.js component. Read more about this solution in the [Quick start](#quick-start) section.
|
|
|
+
|
|
|
+Additionally, you can [integrate CKEditor 5 from source](#using-ckeditor-from-source) which is a much more flexible and powerful solution, but requires some additional configuration.
|
|
|
+
|
|
|
+<info-box>
|
|
|
+ The component is compatible with Vue.js 2.x.
|
|
|
+</info-box>
|
|
|
+
|
|
|
+## Quick start
|
|
|
+
|
|
|
+Install the [CKEditor 5 rich text editor component for Vue.js](https://www.npmjs.com/package/@ckeditor/ckeditor5-vue) and the {@link builds/guides/overview#available-builds build of your choice}.
|
|
|
+
|
|
|
+Assuming that you picked [`@ckeditor/ckeditor5-build-classic`](https://www.npmjs.com/package/@ckeditor/ckeditor5-build-classic):
|
|
|
+
|
|
|
+```bash
|
|
|
+npm install --save @ckeditor/ckeditor5-vue @ckeditor/ckeditor5-build-classic
|
|
|
+```
|
|
|
+
|
|
|
+Now, you need to enable CKEditor component in your application. There are 2 ways to do so:
|
|
|
+
|
|
|
+* [via a direct script include](#direct-script-include),
|
|
|
+* [by using ES6 module imports](#using-es6-modules).
|
|
|
+
|
|
|
+Optionally, you can [use the component locally](#using-component-locally).
|
|
|
+
|
|
|
+### Direct script include
|
|
|
+
|
|
|
+This is the quickest way to start using CKEditor in your project. Assuming [Vue is installed](https://vuejs.org/v2/guide/installation.html), include the `<script>` tags for the editor component and the build:
|
|
|
+
|
|
|
+```html
|
|
|
+<script src="../node_modules/@ckeditor/ckeditor5-build-classic/build/ckeditor.js"></script>
|
|
|
+<script src="../node_modules/@ckeditor/ckeditor5-vue/dist/ckeditor.js"></script>
|
|
|
+```
|
|
|
+
|
|
|
+Enable the component in your application using the [`Vue.use()`](https://vuejs.org/v2/api/#Vue-use) method:
|
|
|
+
|
|
|
+```js
|
|
|
+Vue.use( CKEditor );
|
|
|
+```
|
|
|
+
|
|
|
+<info-box>
|
|
|
+ Instead of calling `Vue.use()`, you can always [use the component locally](#using-component-locally).
|
|
|
+</info-box>
|
|
|
+
|
|
|
+Use the `<ckeditor>` component in your template:
|
|
|
+
|
|
|
+* The [`editor`](#editor) directive specifies the editor build.
|
|
|
+* The [`v-model`](#v-model) directive enables an out–of–the–box two–way data binding.
|
|
|
+* The [`config`](#config) directive helps you pass the configuration to the editor instance.
|
|
|
+
|
|
|
+```html
|
|
|
+<div id="app">
|
|
|
+ <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
|
|
|
+</div>
|
|
|
+```
|
|
|
+
|
|
|
+```js
|
|
|
+const app = new Vue( {
|
|
|
+ el: '#app',
|
|
|
+ data: {
|
|
|
+ editor: ClassicEditor,
|
|
|
+ editorData: '<p>Content of the editor.</p>',
|
|
|
+ editorConfig: {
|
|
|
+ // Configuration of the editor.
|
|
|
+ }
|
|
|
+ }
|
|
|
+} );
|
|
|
+```
|
|
|
+
|
|
|
+Voila! You should see CKEditor 5 running in your Vue.js app.
|
|
|
+
|
|
|
+<info-box>
|
|
|
+ See the list of supported [directives](#component-directives) and [events](#component-events) that will help you configure the component.
|
|
|
+</info-box>
|
|
|
+
|
|
|
+### Using ES6 modules
|
|
|
+
|
|
|
+The editor component comes as a [UMD module](https://github.com/umdjs/umd), which makes it possible to use in various environments, for instance, applications generated by [Vue CLI 3](https://cli.vuejs.org/), built using [webpack](https://webpack.js.org), etc..
|
|
|
+
|
|
|
+To create an editor instance, you must first import the editor build and the component modules into the root file of your application (e.g. `main.js` when generated by Vue CLI). Then, enable the component using the [`Vue.use()`](https://vuejs.org/v2/api/#Vue-use) method:
|
|
|
+
|
|
|
+```js
|
|
|
+import Vue from 'vue';
|
|
|
+import CKEditor from '@ckeditor/ckeditor5-vue';
|
|
|
+
|
|
|
+Vue.use( CKEditor );
|
|
|
+```
|
|
|
+
|
|
|
+<info-box>
|
|
|
+ Instead of calling `Vue.use()`, you can always [use the component locally](#using-component-locally).
|
|
|
+</info-box>
|
|
|
+
|
|
|
+The following example showcases a single–file component of the application. Use the `<ckeditor>` component in your template:
|
|
|
+
|
|
|
+* The [`editor`](#editor) directive specifies the editor build (the editor constructor).
|
|
|
+* The [`v-model`](#v-model) directive enables an out–of–the–box two–way data binding.
|
|
|
+* The [`config`](#config) directive helps you pass the configuration to the editor instance.
|
|
|
+
|
|
|
+```html
|
|
|
+<template>
|
|
|
+ <div id="app">
|
|
|
+ <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
|
|
|
+ </div>
|
|
|
+</template>
|
|
|
+
|
|
|
+<script>
|
|
|
+ import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
|
|
|
+
|
|
|
+ export default {
|
|
|
+ name: 'app',
|
|
|
+ data() {
|
|
|
+ return {
|
|
|
+ editor: ClassicEditor,
|
|
|
+ editorData: '<p>Content of the editor.</p>',
|
|
|
+ editorConfig: {
|
|
|
+ // Configuration of the editor.
|
|
|
+ }
|
|
|
+ };
|
|
|
+ }
|
|
|
+ }
|
|
|
+</script>
|
|
|
+```
|
|
|
+
|
|
|
+<info-box>
|
|
|
+ See the list of supported [directives](#component-directives) and [events](#component-events) that will help you configure the component.
|
|
|
+</info-box>
|
|
|
+
|
|
|
+## Using component locally
|
|
|
+
|
|
|
+If you do not want the CKEditor component to be enabled globally, you can entirely skip the `Vue.use( CKEditor )` part. Instead, configure it in the `components` property of your view.
|
|
|
+
|
|
|
+<info-box>
|
|
|
+ Make sure `CKEditor` and `ClassicEditor` are accessible depending on the integration scenario: as [direct script includes](#direct-script-include) or [ES6 module imports](#using-es6-modules).
|
|
|
+</info-box>
|
|
|
+
|
|
|
+```html
|
|
|
+<template>
|
|
|
+ <div id="app">
|
|
|
+ <ckeditor :editor="editor" ... ></ckeditor>
|
|
|
+ </div>
|
|
|
+</template>
|
|
|
+
|
|
|
+<script>
|
|
|
+ export default {
|
|
|
+ name: 'app',
|
|
|
+ components: {
|
|
|
+ // Use the <ckeditor> component in this view.
|
|
|
+ ckeditor: CKEditor.component
|
|
|
+ },
|
|
|
+ data() {
|
|
|
+ return {
|
|
|
+ editor: ClassicEditor,
|
|
|
+
|
|
|
+ // ...
|
|
|
+ };
|
|
|
+ }
|
|
|
+ }
|
|
|
+</script>
|
|
|
+```
|
|
|
+
|
|
|
+## Using CKEditor from source
|
|
|
+
|
|
|
+Integrating the rich text editor from source allows you to use the full power of the {@link framework/guides/overview CKEditor 5 Framework}.
|
|
|
+
|
|
|
+This guide assumes that you are using [Vue CLI 3+](https://cli.vuejs.org) as your boilerplate and your application has been created using the [`vue create`](https://cli.vuejs.org/guide/creating-a-project.html#vue-create) command.
|
|
|
+
|
|
|
+<info-box>
|
|
|
+ Learn more about building CKEditor from source in the {@link builds/guides/integration/advanced-setup Advanced setup} guide.
|
|
|
+</info-box>
|
|
|
+
|
|
|
+### Configuring `vue.config.js`
|
|
|
+
|
|
|
+To build CKEditor with your application, certain changes must be made to the default project configuration.
|
|
|
+
|
|
|
+First, install the necessary dependencies:
|
|
|
+
|
|
|
+```bash
|
|
|
+npm install --save \
|
|
|
+ @ckeditor/ckeditor5-dev-webpack-plugin \
|
|
|
+ @ckeditor/ckeditor5-dev-utils \
|
|
|
+ postcss-loader \
|
|
|
+ raw-loader
|
|
|
+```
|
|
|
+
|
|
|
+Edit the `vue.config.js` file and use the following configuration. If the file is not present, create it in the root of the application (i.e. next to `package.json`):
|
|
|
+
|
|
|
+```js
|
|
|
+const CKEditorWebpackPlugin = require( '@ckeditor/ckeditor5-dev-webpack-plugin' );
|
|
|
+const { styles } = require( '@ckeditor/ckeditor5-dev-utils' );
|
|
|
+
|
|
|
+module.exports = {
|
|
|
+ // The source of CKEditor is encapsulated in ES6 modules. By default, the code
|
|
|
+ // from node_modules directory is not transpiled, so we must explicitly tell
|
|
|
+ // the CLI tools to transpile JavaScript files in all ckeditor5-* modules.
|
|
|
+ transpileDependencies: [
|
|
|
+ /ckeditor5-[^/\\]+[/\\]src[/\\].+\.js$/,
|
|
|
+ ],
|
|
|
+
|
|
|
+ configureWebpack: {
|
|
|
+ plugins: [
|
|
|
+ // CKEditor needs its own plugin to be built using webpack.
|
|
|
+ new CKEditorWebpackPlugin( {
|
|
|
+ // See https://ckeditor.com/docs/ckeditor5/latest/features/ui-language.html
|
|
|
+ language: 'en'
|
|
|
+ } )
|
|
|
+ ]
|
|
|
+ },
|
|
|
+
|
|
|
+ css: {
|
|
|
+ loaderOptions: {
|
|
|
+ // Various modules in the CKEditor source code import .css files.
|
|
|
+ // These files must be transpiled using PostCSS in order to load properly.
|
|
|
+ postcss: styles.getPostCssConfig( {
|
|
|
+ themeImporter: {
|
|
|
+ themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
|
|
|
+ },
|
|
|
+ minify: true
|
|
|
+ } )
|
|
|
+ }
|
|
|
+ },
|
|
|
+
|
|
|
+ chainWebpack: config => {
|
|
|
+ // Vue CLI would normally use own loader to load .svg files. The icons used by
|
|
|
+ // CKEditor should be loaded using the raw-loader instead.
|
|
|
+ config.module
|
|
|
+ .rule( 'svg' )
|
|
|
+ .test( /ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/ )
|
|
|
+ .use( 'file-loader' )
|
|
|
+ .loader( 'raw-loader' );
|
|
|
+ }
|
|
|
+};
|
|
|
+```
|
|
|
+
|
|
|
+### Using the editor from source
|
|
|
+
|
|
|
+Having configured `vue.config.js`, you can choose the building blocks of your editor. Install the packages necessary for your integration:
|
|
|
+
|
|
|
+```bash
|
|
|
+npm install --save \
|
|
|
+ @ckeditor/ckeditor5-editor-classic \
|
|
|
+ @ckeditor/ckeditor5-essentials \
|
|
|
+ @ckeditor/ckeditor5-basic-styles \
|
|
|
+ @ckeditor/ckeditor5-basic-styles \
|
|
|
+ @ckeditor/ckeditor5-link \
|
|
|
+ @ckeditor/ckeditor5-paragraph
|
|
|
+```
|
|
|
+
|
|
|
+You can use more packages, depending on which features are needed in your application.
|
|
|
+
|
|
|
+```js
|
|
|
+import CKEditor from '@ckeditor/ckeditor5-vue';
|
|
|
+
|
|
|
+Vue.use( CKEditor );
|
|
|
+```
|
|
|
+
|
|
|
+<info-box>
|
|
|
+ Instead of calling `Vue.use()`, you can always [use the component locally](#using-component-locally).
|
|
|
+</info-box>
|
|
|
+
|
|
|
+Now all you need to do is specify the list of editor options (**including plugins**) in the `editorConfig` data property:
|
|
|
+
|
|
|
+```html
|
|
|
+<template>
|
|
|
+ <div id="app">
|
|
|
+ <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
|
|
|
+ </div>
|
|
|
+</template>
|
|
|
+
|
|
|
+<script>
|
|
|
+ import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
|
|
|
+
|
|
|
+ import EssentialsPlugin from '@ckeditor/ckeditor5-essentials/src/essentials';
|
|
|
+ import BoldPlugin from '@ckeditor/ckeditor5-basic-styles/src/bold';
|
|
|
+ import ItalicPlugin from '@ckeditor/ckeditor5-basic-styles/src/italic';
|
|
|
+ import LinkPlugin from '@ckeditor/ckeditor5-link/src/link';
|
|
|
+ import ParagraphPlugin from '@ckeditor/ckeditor5-paragraph/src/paragraph';
|
|
|
+
|
|
|
+ export default {
|
|
|
+ name: 'app',
|
|
|
+ data() {
|
|
|
+ return {
|
|
|
+ editor: ClassicEditor,
|
|
|
+ editorData: '<p>Content of the editor.</p>',
|
|
|
+ editorConfig: {
|
|
|
+ plugins: [
|
|
|
+ EssentialsPlugin,
|
|
|
+ BoldPlugin,
|
|
|
+ ItalicPlugin,
|
|
|
+ LinkPlugin,
|
|
|
+ ParagraphPlugin
|
|
|
+ ],
|
|
|
+
|
|
|
+ toolbar: {
|
|
|
+ items: [
|
|
|
+ 'bold',
|
|
|
+ 'italic',
|
|
|
+ 'link',
|
|
|
+ 'undo',
|
|
|
+ 'redo'
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ }
|
|
|
+ };
|
|
|
+ }
|
|
|
+ };
|
|
|
+</script>
|
|
|
+```
|
|
|
+
|
|
|
+## Component directives
|
|
|
+
|
|
|
+### `editor`
|
|
|
+
|
|
|
+This directive specifies the editor to be used by the component. It must directly reference the editor constructor to be used in the template.
|
|
|
+
|
|
|
+```html
|
|
|
+<template>
|
|
|
+ <div id="app">
|
|
|
+ <ckeditor :editor="editor" ... ></ckeditor>
|
|
|
+ </div>
|
|
|
+</template>
|
|
|
+
|
|
|
+<script>
|
|
|
+ import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
|
|
|
+
|
|
|
+ export default {
|
|
|
+ name: 'app',
|
|
|
+ data() {
|
|
|
+ return {
|
|
|
+ editor: ClassicEditor,
|
|
|
+
|
|
|
+ // ...
|
|
|
+ };
|
|
|
+ }
|
|
|
+ }
|
|
|
+</script>
|
|
|
+```
|
|
|
+
|
|
|
+<info-box>
|
|
|
+ To use more than one rich text editor build in your application, you will need to configure it [from source](#using-ckeditor-from-source) or use a {@link builds/guides/integration/advanced-setup#scenario-3-using-two-different-editors "super build"}.
|
|
|
+</info-box>
|
|
|
+
|
|
|
+### `tag-name`
|
|
|
+
|
|
|
+By default, the editor component creates a `<div>` container which is used as an element passed to the editor (e.g. {@link module:editor-classic/classiceditor~ClassicEditor#element `ClassicEditor#element`}). The element can be configured, e.g. to create a `<textarea>` use the following directive:
|
|
|
+
|
|
|
+```html
|
|
|
+<ckeditor :editor="editor" tag-name="textarea"></ckeditor>
|
|
|
+```
|
|
|
+
|
|
|
+### `v-model`
|
|
|
+
|
|
|
+A [standard directive](https://vuejs.org/v2/api/#v-model) for form inputs in Vue. Unlike [`value`](#value), it creates a two–way data binding, which:
|
|
|
+
|
|
|
+* sets the initial editor content,
|
|
|
+* automatically updates the state of the application as the editor content changes (e.g. as the user types),
|
|
|
+* can be used to set editor content when necessary.
|
|
|
+
|
|
|
+```html
|
|
|
+<template>
|
|
|
+ <div id="app">
|
|
|
+ <ckeditor :editor="editor" v-model="editorData"></ckeditor>
|
|
|
+ <button v-on:click="emptyEditor()">Empty the editor</button>
|
|
|
+
|
|
|
+ <h2>Editor data</h2>
|
|
|
+ <code>{{ editorData }}</code>
|
|
|
+ </div>
|
|
|
+</template>
|
|
|
+
|
|
|
+<script>
|
|
|
+ import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
|
|
|
+
|
|
|
+ export default {
|
|
|
+ name: 'app',
|
|
|
+ data() {
|
|
|
+ return {
|
|
|
+ editor: ClassicEditor,
|
|
|
+ editorData: '<p>Content of the editor.</p>'
|
|
|
+ };
|
|
|
+ },
|
|
|
+ methods: {
|
|
|
+ emptyEditor() {
|
|
|
+ this.editorData = '';
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+</script>
|
|
|
+```
|
|
|
+
|
|
|
+In the above example, the `editorData` property will be updated automatically as the user types and changes the content. It can also be used to change (as in `emptyEditor()`) or set the initial content of the editor.
|
|
|
+
|
|
|
+If you only want to execute an action when the editor data changes, use the [`input`](#input) event.
|
|
|
+
|
|
|
+### `value`
|
|
|
+
|
|
|
+Allows a one–way data binding that sets the content of the editor. Unlike [`v-model`](#v-model), the value will not be updated when as the content of the editor changes.
|
|
|
+
|
|
|
+```html
|
|
|
+<template>
|
|
|
+ <div id="app">
|
|
|
+ <ckeditor :editor="editor" :value="editorData"></ckeditor>
|
|
|
+ </div>
|
|
|
+</template>
|
|
|
+
|
|
|
+<script>
|
|
|
+ import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
|
|
|
+
|
|
|
+ export default {
|
|
|
+ name: 'app',
|
|
|
+ data() {
|
|
|
+ return {
|
|
|
+ editor: ClassicEditor,
|
|
|
+ editorData: '<p>Content of the editor.</p>'
|
|
|
+ };
|
|
|
+ }
|
|
|
+ }
|
|
|
+</script>
|
|
|
+```
|
|
|
+
|
|
|
+To execute an action when the editor data changes, use the [`input`](#input) event.
|
|
|
+
|
|
|
+### `config`
|
|
|
+
|
|
|
+Specifies the {@link module:core/editor/editorconfig~EditorConfig configuration} of the editor.
|
|
|
+
|
|
|
+```html
|
|
|
+<template>
|
|
|
+ <div id="app">
|
|
|
+ <ckeditor :editor="editor" :config="editorConfig"></ckeditor>
|
|
|
+ </div>
|
|
|
+</template>
|
|
|
+
|
|
|
+<script>
|
|
|
+ import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
|
|
|
+
|
|
|
+ export default {
|
|
|
+ name: 'app',
|
|
|
+ data() {
|
|
|
+ return {
|
|
|
+ editor: ClassicEditor,
|
|
|
+ editorConfig: {
|
|
|
+ toolbar: [ 'bold', 'italic', '|' 'link' ]
|
|
|
+ }
|
|
|
+ };
|
|
|
+ }
|
|
|
+ }
|
|
|
+</script>
|
|
|
+```
|
|
|
+
|
|
|
+### `disabled`
|
|
|
+
|
|
|
+This directive controls the {@link module:core/editor/editor~Editor#isReadOnly `isReadOnly`} property of the editor.
|
|
|
+
|
|
|
+It sets the initial read–only state of the editor and changes it during its lifecycle.
|
|
|
+
|
|
|
+```html
|
|
|
+<template>
|
|
|
+ <div id="app">
|
|
|
+ <ckeditor :editor="editor" :disabled="editorDisabled"></ckeditor>
|
|
|
+ </div>
|
|
|
+</template>
|
|
|
+
|
|
|
+<script>
|
|
|
+ import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
|
|
|
+
|
|
|
+ export default {
|
|
|
+ name: 'app',
|
|
|
+ data() {
|
|
|
+ return {
|
|
|
+ editor: ClassicEditor,
|
|
|
+ // This editor will be read–only when created.
|
|
|
+ editorDisabled: true
|
|
|
+ };
|
|
|
+ }
|
|
|
+ }
|
|
|
+</script>
|
|
|
+```
|
|
|
+
|
|
|
+## Component events
|
|
|
+
|
|
|
+### `ready`
|
|
|
+
|
|
|
+Corresponds to the {@link module:core/editor/editor~Editor#event:ready `ready`} editor event.
|
|
|
+
|
|
|
+```html
|
|
|
+<ckeditor :editor="editor" @ready="onEditorReady"></ckeditor>
|
|
|
+```
|
|
|
+
|
|
|
+### `focus`
|
|
|
+
|
|
|
+Corresponds to the {@link module:engine/view/document~Document#event:focus `focus`} editor event.
|
|
|
+
|
|
|
+```html
|
|
|
+<ckeditor :editor="editor" @focus="onEditorFocus"></ckeditor>
|
|
|
+```
|
|
|
+
|
|
|
+### `blur`
|
|
|
+
|
|
|
+Corresponds to the {@link module:engine/view/document~Document#event:blur `blur`} editor event.
|
|
|
+
|
|
|
+```html
|
|
|
+<ckeditor :editor="editor" @blur="onEditorBlur"></ckeditor>
|
|
|
+```
|
|
|
+
|
|
|
+### `input`
|
|
|
+
|
|
|
+Corresponds to the {@link module:engine/model/document~Document#event:change:data `change:data`} editor event. See the [`v-model` directive](#v-model) to learn more.
|
|
|
+
|
|
|
+```html
|
|
|
+<ckeditor :editor="editor" @input="onEditorInput"></ckeditor>
|
|
|
+```
|
|
|
+
|
|
|
+### `destroy`
|
|
|
+
|
|
|
+Corresponds to the {@link module:core/editor/editor~Editor#event:destroy `destroy`} editor event.
|
|
|
+
|
|
|
+**Note:** Because the destruction of the editor is promise–driven, this event can be fired before the actual promise resolves.
|
|
|
+
|
|
|
+```html
|
|
|
+<ckeditor :editor="editor" @destroy="onEditorDestroy"></ckeditor>
|
|
|
+```
|
|
|
+
|
|
|
+## Contributing and reporting issues
|
|
|
+
|
|
|
+The source code of this component is available on GitHub in https://github.com/ckeditor/ckeditor5-vue.
|