8
0
Просмотр исходного кода

Merge branch 'master' into t/ckeditor5-vue/1

Aleksander Nowodzinski 7 лет назад
Родитель
Сommit
243ea14eca
2 измененных файлов с 649 добавлено и 3 удалено
  1. 4 3
      docs/builds/guides/frameworks/overview.md
  2. 645 0
      docs/builds/guides/frameworks/vuejs.md

+ 4 - 3
docs/builds/guides/frameworks/overview.md

@@ -18,7 +18,7 @@ When checking how to integrate CKEditor 5 with your framework you can follow the
 
 1. **Check whether an [official integration](#official-rich-text-editor-integrations) exists.**
 
-	There are two official integrations so far: for {@link builds/guides/frameworks/react React} and for {@link builds/guides/frameworks/angular Angular 2+}.
+	There are three official integrations so far: for {@link builds/guides/frameworks/react React}, {@link builds/guides/frameworks/angular Angular 2+}, and for {@link builds/guides/frameworks/vuejs Vue.js}.
 2. **If not, search for community-driven integrations.** Most of them are available on [npm](https://www.npmjs.com/).
 3. **If none exists, integrate CKEditor 5 with your framework by yourself.**
 
@@ -26,10 +26,11 @@ When checking how to integrate CKEditor 5 with your framework you can follow the
 
 ## Official WYSIWYG editor integrations
 
-There are two official integrations so far:
+There are three official integrations so far:
 
-* {@link builds/guides/frameworks/react CKEditor 5 rich-text editor for React}
 * {@link builds/guides/frameworks/angular CKEditor 5 rich-text editor for Angular 2+}
+* {@link builds/guides/frameworks/react CKEditor 5 rich-text editor for React}
+* {@link builds/guides/frameworks/vuejs CKEditor 5 rich-text editor for Vue.js}
 
 Refer to their documentation to learn how to use them.
 

+ 645 - 0
docs/builds/guides/frameworks/vuejs.md

@@ -0,0 +1,645 @@
+---
+menu-title: Vue.js component
+category: builds-integration-frameworks
+order: 40
+---
+
+# Rich text editor component for Vue.js
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-vue.svg)](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 [configure the component locally](#using-the-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, specifying the editor build you want to use:
+
+```js
+Vue.use( CKEditor, {
+	editors: {
+		classic: ClassicEditor
+	}
+} );
+```
+
+<info-box>
+	Check out the [component configuration](#component-configuration) section to learn more about the available options.
+</info-box>
+
+<info-box>
+	You can always configure the component locally if you do not want to [specify editor builds](#local-configuration) at that point or just to [avoid using `Vue.use()`](#local-component-registration).
+</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="classic" v-model="editorData" :config="editorConfig"></ckeditor>
+</div>
+```
+
+```js
+const app = new Vue( {
+	el: '#app',
+	data: {
+		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, specifying the editor builds you want to use:
+
+```js
+import Vue from 'vue';
+import CKEditor from '@ckeditor/ckeditor5-vue';
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+
+Vue.use( CKEditor, {
+	editors: {
+		classic: ClassicEditor
+	}
+} );
+```
+
+<info-box>
+	Check out the [component configuration](#component-configuration) section to learn more.
+</info-box>
+
+<info-box>
+	You can always configure the component locally if you do not want to [specify editor builds](#local-configuration) at that point or just to [avoid using `Vue.use()`](#local-component-registration).
+</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 [`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="classic" v-model="editorData" :config="editorConfig"></ckeditor>
+	</div>
+</template>
+
+<script>
+	export default {
+		name: 'app',
+		data() {
+			return {
+				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 the component locally
+
+### Local configuration
+
+If a per–view editor configuration is what suits you best, you can skip the [`editors`](#editors) option in `Vue.use()` when enabling the component.
+
+<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>
+
+```js
+Vue.use( CKEditor );
+```
+
+and then pass the editor of your choice in the [`editor`](#editor) directive:
+
+```html
+<template>
+	<div id="app">
+		<ckeditor :editor="editorType" ... ></ckeditor>
+	</div>
+</template>
+
+<script>
+	export default {
+		name: 'app',
+		data() {
+			return {
+				editorType: ClassicEditor,
+
+				// ...
+			};
+		}
+	}
+</script>
+```
+
+### Local component registration
+
+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="editorType" ... ></ckeditor>
+	</div>
+</template>
+
+<script>
+	export default {
+		name: 'app',
+		components: {
+			// Use the CKEditor component in this view.
+			ckeditor: CKEditor.component
+		},
+		data() {
+			return {
+				editorType: 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.
+
+Make sure your editor is [available to the component](#editors) (e.g. in `main.js`):
+
+```js
+import CKEditor from '@ckeditor/ckeditor5-vue';
+
+import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
+
+Vue.use( CKEditor, {
+	editors: {
+		classic: ClassicEditor
+	}
+} );
+```
+
+<info-box>
+	You can always configure the component locally if you do not want to [specify the editors](#local-configuration) at that point or just to [avoid using `Vue.use()`](#local-component-registration).
+</info-box>
+
+Now all you need to do is specify `classic` in the [`editor`](#editor) directive and the list of editor options (**including plugins**) in the `editorConfig` data property:
+
+```html
+<template>
+	<div id="app">
+		<ckeditor editor="classic" v-model="editorData" :config="editorConfig"></ckeditor>
+	</div>
+</template>
+
+<script>
+	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 {
+				editorData: '<p>Content of the editor.</p>',
+				editorConfig: {
+					plugins: [
+						EssentialsPlugin,
+						BoldPlugin,
+						ItalicPlugin,
+						LinkPlugin,
+						ParagraphPlugin
+					],
+
+					toolbar: {
+						items: [
+							'bold',
+							'italic',
+							'link',
+							'undo',
+							'redo'
+						]
+					}
+				}
+			};
+		}
+	};
+</script>
+```
+
+## Component configuration
+
+<info-box>
+	You can entirely skip the configuration part if you decide to [configure the component locally](#using-the-component-locally).
+</info-box>
+
+### `editors`
+
+This configuration specifies editors available to the component. You can use {@link builds/guides/overview ready-to-use builds} or [editors from source](#using-ckeditor-from-source):
+
+```js
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+
+Vue.use( CKEditor, {
+	editors: {
+		classic: ClassicEditor,
+
+		// ...
+	}
+} );
+```
+
+Use the [name of the editor](#editor) in your template to create the editor instance of your choice:
+
+```html
+<ckeditor editor="classic"></ckeditor>
+```
+
+<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>
+
+<info-box>
+	You can skip this configuration and [pass the editor directly](#local-configuration) in the [`editor`](#editor) directive.
+</info-box>
+
+### `componentName`
+
+You can change the name of the CKEditor component using the `componentName` property (by default `<ckeditor>`):
+
+```js
+Vue.use( CKEditor, {
+	componentName: 'myEditor'
+} );
+```
+
+Use the new component name in the template to create editor instances:
+
+```html
+<myEditor editor="classic"></myEditor>
+```
+
+## Component directives
+
+### `editor`
+
+This directive specifies the editor to be used by the component. It should either:
+
+* correspond to one of [registered editors](#editors):
+	```js
+	import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+
+	Vue.use( CKEditor, {
+		editors: {
+			classic: ClassicEditor,
+
+			// ...
+		}
+	} );
+	```
+
+	```html
+	<ckeditor editor="classic"></ckeditor>
+	```
+
+* [directly reference](#local-configuration) the editor to be used in the template:
+	```html
+	<template>
+		 <div id="app">
+			  <ckeditor :editor="editorType" ... ></ckeditor>
+		 </div>
+	</template>
+
+	<script>
+		export default {
+			name: 'app',
+			data() {
+				return {
+					editorType: 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 tothe 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="classic" 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="classic" v-model="editorData"></ckeditor>
+		<button v-on:click="emptyEditor()">Empty the editor</button>
+
+		<h2>Editor data</h2>
+		<code>{{ editorData }}</code>
+	</div>
+</template>
+
+<script>
+	export default {
+		name: 'app',
+		data() {
+			return {
+				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="classic" :value="editorData"></ckeditor>
+	</div>
+</template>
+
+<script>
+	export default {
+		name: 'app',
+		data() {
+			return {
+				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="classic" :config="editorConfig"></ckeditor>
+	</div>
+</template>
+
+<script>
+	export default {
+		name: 'app',
+		data() {
+			return {
+				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="classic" :disabled="editorDisabled"></ckeditor>
+	</div>
+</template>
+
+<script>
+	export default {
+		name: 'app',
+		data() {
+			return {
+				// 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="classic" @ready="onEditorReady"></ckeditor>
+```
+
+### `focus`
+
+Corresponds to the {@link module:engine/view/document~Document#event:focus `focus`} editor event.
+
+```html
+<ckeditor editor="classic" @focus="onEditorFocus"></ckeditor>
+```
+
+### `blur`
+
+Corresponds to the {@link module:engine/view/document~Document#event:blur `blur`} editor event.
+
+```html
+<ckeditor editor="classic" @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="classic" @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="classic" @destroy="onEditorDestroy"></ckeditor>
+```
+
+## Contributing and reporting issues
+
+The source code of this component is available on GitHub in https://github.com/ckeditor/ckeditor5-vue.