Skip to content

Latest commit

 

History

History
537 lines (410 loc) · 15.2 KB

vuejs.md

File metadata and controls

537 lines (410 loc) · 15.2 KB
Raw
menu-title category order
Vue.js component
builds-integration-frameworks
40

Rich text editor component for Vue.js

npm version

CKEditor 5 consists of {@link builds/guides/overview ready-to-use editor builds} and {@link framework/guides/overview CKEditor 5 Framework} upon which the builds are based.

The easiest way 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 section.

Additionally, you can integrate CKEditor 5 from source which is a much more flexible and powerful solution, but requires some additional configuration.

The component is compatible with Vue.js 2.x.

Quick start

Install the CKEditor 5 WYSIWYG editor component for Vue.js and the {@link builds/guides/overview#available-builds build of your choice}.

Assuming that you picked @ckeditor/ckeditor5-build-classic:

npm install --save @ckeditor/ckeditor5-vue @ckeditor/ckeditor5-build-classic

You now need to enable the CKEditor component in your application. There are 2 ways to do so:

Optionally, you can use the component locally.

Direct script include

This is the quickest way to start using CKEditor in your project. Assuming Vue is installed, include the <script> tags for the WYSIWYG editor component and the build:

<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 by using the Vue.use() method:

Vue.use( CKEditor );
Instead of calling `Vue.use()`, you can always [use the component locally](#using-component-locally).

Use the <ckeditor> component in your template:

  • The editor directive specifies the editor build.
  • The v-model directive enables an out–of–the–box two–way data binding.
  • The config directive helps you pass the configuration to the editor instance.
<div id="app">
	<ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
</div>
const app = new Vue( {
	el: '#app',
	data: {
		editor: ClassicEditor,
		editorData: '<p>Content of the editor.</p>',
		editorConfig: {
			// The configuration of the editor.
		}
	}
} );

Voilà! You should see CKEditor 5 running in your Vue.js app.

See the list of supported [directives](#component-directives) and [events](#component-events) that will help you configure the component.

Using ES6 modules

The editor component comes as a UMD module, which makes it possible to use in various environments, for instance, applications generated by Vue CLI 3, built using webpack, 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() method:

import Vue from 'vue';
import CKEditor from '@ckeditor/ckeditor5-vue';

Vue.use( CKEditor );
Instead of calling `Vue.use()`, you can always [use the component locally](#using-component-locally).

The following example showcases a single–file component of the application. Use the <ckeditor> component in your template:

  • The editor directive specifies the editor build (the editor constructor).
  • The v-model directive enables an out–of–the–box two–way data binding.
  • The config directive helps you pass the configuration to the editor instance.
<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: {
					// The configuration of the editor.
				}
			};
		}
	}
</script>
See the list of supported [directives](#component-directives) and [events](#component-events) that will help you configure the component.

Using component locally

If you do not want the CKEditor component to be enabled globally, you can skip the Vue.use( CKEditor ) part entirely. Instead, configure it in the components property of your view.

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). 
<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 {@link framework/guides/overview CKEditor 5 Framework}.

This guide assumes that you are using Vue CLI 3+ as your boilerplate and your application has been created using the vue create command.

Learn more about building CKEditor from source in the {@link builds/guides/integration/advanced-setup Advanced setup} guide.

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:

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

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 the node_modules directory is not transpiled, so you 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 its own loader to load .svg files. The icons used by
		// CKEditor should be loaded using 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:

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.

import CKEditor from '@ckeditor/ckeditor5-vue';

Vue.use( CKEditor );
Instead of calling `Vue.use()`, you can always [use the component locally](#using-component-locally).

Now all you need to do is specify the list of rich text editor options (including plugins) in the editorConfig data property:

<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.

<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>
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"}.

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, so for example to create a <textarea>, use the following directive:

<ckeditor :editor="editor" tag-name="textarea"></ckeditor>

v-model

A standard directive for form inputs in Vue. Unlike 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 the editor content when necessary.
<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 event.

value

Allows a one–way data binding that sets the content of the editor. Unlike v-model, the value will not be updated when the content of the editor changes.

<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 event.

config

Specifies the {@link module:core/editor/editorconfig~EditorConfig configuration} of the editor.

<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.

<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.

<ckeditor :editor="editor" @ready="onEditorReady"></ckeditor>

focus

Corresponds to the {@link module:engine/view/document~Document#event:focus focus} editor event.

<ckeditor :editor="editor" @focus="onEditorFocus"></ckeditor>

blur

Corresponds to the {@link module:engine/view/document~Document#event:blur blur} editor event.

<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 to learn more.

<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.

<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.