8
0
Quellcode durchsuchen

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

Piotrek Koszuliński vor 7 Jahren
Ursprung
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
 

+ 31 - 16
docs/framework/guides/architecture/editing-engine.md

@@ -198,7 +198,7 @@ What this means is that:
 
 * The view is yet another custom structure.
 * It resembles the DOM. While the model's tree structure only slightly resembled the DOM (e.g. by introducing text attributes), the view is much closer to the DOM. In other words, it is a **virtual DOM**.
-* There are two "pipelines": the **editing pipeline** (also called the "editing view") and the **data pipeline** ("the data view"). Treat them as two separate views of one model. The editing pipeline renders and handles the DOM that the user sees and can edit. The data pipeline is used when you call `editor.getData()`, `editor.setData()` or paste content into the editor.
+* There are two "pipelines": the **editing pipeline** (also called the "editing view") and the **data pipeline** (the "data view"). Treat them as two separate views of one model. The editing pipeline renders and handles the DOM that the user sees and can edit. The data pipeline is used when you call `editor.getData()`, `editor.setData()` or paste content into the editor.
 * The views are rendered to the DOM by the {@link module:engine/view/renderer~Renderer} which handles all the quirks required to tame the `contentEditable` used in the editing pipeline.
 
 The fact that there are two views is visible in the API:
@@ -218,20 +218,6 @@ editor.data;                    // The data pipeline (DataController).
 	Check out the {@link module:engine/controller/editingcontroller~EditingController}'s and {@link module:engine/controller/datacontroller~DataController}'s API.
 </info-box>
 
-### Changing the view
-
-Do not change the view manually, unless you really know what you are doing. If the view needs to be changed, in most cases, it means that the model should be changed first. Then the changes you apply to the model are converted ([conversion](#conversion) is covered below) to the view by specific converters.
-
-The view may need to be changed manually if the cause of such change is not represented in the model. For example, the model does not store information about the focus, which is a {@link module:engine/view/document~Document#isFocused property of the view}. When the focus changes, and you want to represent that in some element's class, you need to change that class manually.
-
-For that, just like in the model, you should use the `change()` block (of the view) in which you will have access to the view writer.
-
-```js
-editor.data.view.change( writer => {
-	writer.insert( position1, writer.createText( 'foo' ) );
-} );
-```
-
 ### Element types and custom data
 
 The structure of the view resembles the structure in the DOM very closely. The semantics of HTML is defined in its specification. The view structure comes "DTD-free", so in order to provide additional information and better express the semantics of the content, the view structure implements 5 element types ({@link module:engine/view/containerelement~ContainerElement}, {@link module:engine/view/attributeelement~AttributeElement}, {@link module:engine/view/emptyelement~EmptyElement}, {@link module:engine/view/uielement~UIElement}, and {@link module:engine/view/editableelement~EditableElement}) and so called {@link module:engine/view/element~Element#getCustomProperty "custom properties"} (i.e. custom element properties which are not rendered). This additional information provided by editor features is then used by the {@link module:engine/view/renderer~Renderer} and [converters](#Conversion).
@@ -244,12 +230,41 @@ The element types can be defined as follows:
 * **UI elements** &ndash; The elements that are not a part of the "data" but need to be "inlined" in the content. They are ignored by the selection (it jumps over them) and the view writer in general. The contents of these elements and events coming from them are filtered out, too.
 * **Editable element** &ndash; The elements used as "nested editables" of non-editable fragments of the content, for example a caption in the image widget, where the `<figure>` wrapping the image is not editable (it is a widget) and the `<figcaption>` inside it is an editable element.
 
-Custom properties are used to store information like:
+Additionally, you can define {@link module:engine/view/element~Element#getCustomProperty custom properties} which can be used to store information like:
 
 * Whether an element is a widget (added by {@link module:widget/utils~toWidget `toWidget()`}).
 * How an element should be marked when a [marker](#markers) highlights it.
 * Whether an element belongs to a certain feature &mdash; if it is a link, progress bar, caption, etc.
 
+#### Non-semantic views
+
+Not all view trees need to (and can) be build with semantic element types. View structures generated straight from input data (e.g. pasted HTML or with `editor.setData()`) consists only of {@link module:engine/view/element~Element base element} instances. Those view structures are (usually) [converted to model structures](#conversion) and then converted back to view structures for editing or data retrieval purposes, at which point they become semantic views again.
+
+The additional information conveyed in the semantic views and special types of operations that feature developers want to perform on those tree (compared to simple tree operations on non-semantic views) means that both structures need to be [modified by different tools](#changing-the-view).
+
+We will explain the [conversion](#conversion) later in this guide. For now, it is only important for you to know that there are semantic views for rendering and data retrieval purposes and non-semantic views for data input.
+
+### Changing the view
+
+Do not change the view manually, unless you really know what you are doing. If the view needs to be changed, in most cases, it means that the model should be changed first. Then the changes you apply to the model are converted ([conversion](#conversion) is covered below) to the view by specific converters.
+
+The view may need to be changed manually if the cause of such change is not represented in the model. For example, the model does not store information about the focus, which is a {@link module:engine/view/document~Document#isFocused property of the view}. When the focus changes, and you want to represent that in some element's class, you need to change that class manually.
+
+For that, just like in the model, you should use the `change()` block (of the view) in which you will have access to the view downcast writer.
+
+```js
+editor.data.view.change( writer => {
+	writer.insert( position1, writer.createText( 'foo' ) );
+} );
+```
+
+<info-box>
+	There are two view writers:
+
+	* {@link module:engine/view/downcastwriter~DowncastWriter} &mdash; available in the `change()` blocks, used during downcasting the model to the view. It operates on a "semantic view" so a view structure which differentiates between different types of elements (see [Element types and custom data](#element-types-and-custom-data)).
+	* {@link module:engine/view/upcastwriter~UpcastWriter} &mdash; a writer to be used when pre-processing the "input" data (e.g. pasted content) which happens usually before the conversion (upcasting) to the model. It operates on ["non-semantic views"](#non-semantic-views).
+</info-box>
+
 ### Positions
 
 Just like [in the model](#positions-ranges-and-selections), in the view there are 3 levels of classes that describe points in the view structure: **positions**, **ranges** and **selections**. A position is a single point in the document. A range consists of two positions (start and end). And selection consists of one or more ranges and has a direction (whether it was done from left to right or from right to left).

+ 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",