Browse Source

Merge branch 'master' into t/ckeditor5-angular/36

Piotrek Koszuliński 7 years ago
parent
commit
21c8de8281

+ 1 - 1
README.md

@@ -14,7 +14,7 @@ CKEditor 5 [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?styl
 
 A set of ready-to-use rich text editors created with a powerful framework. Made with real-time collaborative editing in mind.
 
-![CKEditor 5 Classic rich text editor build screenshot](https://c.cksource.com/a/1/img/npm/ckeditor%205%20classic%20screeshot.png)
+![CKEditor 5 Classic rich text editor build screenshot](https://c.cksource.com/a/1/img/npm/ckeditor5-build-classic.png)
 
 ## ⚠ This package does not contain any source code
 

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

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

@@ -0,0 +1,534 @@
+---
+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 [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.

+ 1 - 8
docs/builds/guides/support/browser-compatibility.md

@@ -29,13 +29,6 @@ Not supported yet:
 
 * Internet Explorer 11. See the [Compatibility with IE11](https://github.com/ckeditor/ckeditor5/issues/330) ticket.
 
-### Notes
-
-Features known to not be fully supported yet:
-
-* Text composition. Input Method Engine (IME) is a mechanism that allows the users to input text in languages such as Japanese and Chinese. This mechanism is not fully supported yet and we will be polishing that feature in a close future.
-* Drag and drop inside the editor does not work yet. It is possible to drop images from your system if the {@link module:image/imageupload~ImageUpload} feature is enabled.
-
 ## Mobile environment
 
 CKEditor 5 is currently supported in the following mobile environments:
@@ -47,6 +40,6 @@ CKEditor 5 is currently supported in the following mobile environments:
 
 ## Quality assurance
 
-To ensure the highest quality, we maintain a complete test suite with a stable 100% of code coverage for each of the packages. As of April 2018, this means over 8200 tests and the number is growing.
+To ensure the highest quality, we maintain a complete test suite with a stable 100% of code coverage for each of the packages. As of October 2018, this means over 9600 tests and the number is growing.
 
 Such an extensive test suite requires a proper continuous integration service. We use [Travis CI](https://travis-ci.com/) as a build platform and [BrowserStack](https://www.browserstack.com/) to be able to run tests on all browsers. These services ensure seamless and fast developer experience and allow us to focus on the job.

+ 4 - 2
docs/builds/guides/support/license-and-legal.md

@@ -14,12 +14,14 @@ Copyright (c) 2003-2018, CKSource Frederico Knabben. All rights reserved.
 
 Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/old-licenses/gpl-2.0.html).
 
+## Free for Open Source
+
+If you are running a project with an OSS license incompatible with GPL, please [contact us](https://ckeditor.com/contact/) and we will be happy to support it with a free CKEditor 5 license.
+
 ## Sources of intellectual property included in CKEditor
 
 Where not otherwise indicated, all CKEditor 5 Builds content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.
 
-The {@link features/image-upload#easy-image Easy Image} feature present in {@link builds/index CKEditor 5 Builds} integrates with [CKEditor Cloud Services](https://ckeditor.com/ckeditor-cloud-services), if configured to do so. CKEditor Cloud Services is an external "Software as a Service" solution, delivered with its own license terms and conditions.
-
 ## Trademarks
 
 CKEditor is a trademark of [CKSource](http://cksource.com/) Frederico Knabben. All other brand and product names are trademarks, registered trademarks or service marks of their respective holders.

+ 5 - 1
docs/framework/guides/architecture/core-editor-architecture.md

@@ -195,6 +195,10 @@ class Command {
 mix( Command, ObservableMixin );
 ```
 
+<info-box>
+	Check out the {@link framework/guides/deep-dive/observables deep dive into observables} guide to learn more about the advanced usage of observables with some additional examples.
+</info-box>
+
 Besides decorating methods with events, observables allow to observe their chosen properties. For instance, the `Command` class makes its `#value` and `#isEnabled` observable by calling {@link module:utils/observablemixin~ObservableMixin#set `set()`}:
 
 ```js
@@ -239,7 +243,7 @@ source.bar = 1;
 target.foo; // -> 1
 ```
 
-You can find more about bindings in the {@link framework/guides/architecture/ui-library UI library architecture} guide.
+You can also find more about data bindings in the user interface in the {@link framework/guides/architecture/ui-library UI library architecture} guide.
 
 ## Read next
 

File diff suppressed because it is too large
+ 31 - 16
docs/framework/guides/architecture/editing-engine.md


+ 2 - 2
package.json

@@ -64,8 +64,8 @@
   "devDependencies": {
     "@ckeditor/ckeditor5-collaboration": "^11.0.0",
     "@ckeditor/ckeditor5-dev-docs": "^10.0.3",
-    "@ckeditor/ckeditor5-dev-env": "^13.0.0",
-    "@ckeditor/ckeditor5-dev-tests": "^13.0.0",
+    "@ckeditor/ckeditor5-dev-env": "^13.0.1",
+    "@ckeditor/ckeditor5-dev-tests": "^13.1.0",
     "@ckeditor/ckeditor5-dev-utils": "^11.0.0",
     "@ckeditor/ckeditor5-dev-webpack-plugin": "^7.0.0",
     "css-loader": "^1.0.0",