Browse Source

Merge pull request #1248 from ckeditor/t/1213

Docs: Introduced the "Frameworks" section. Closes #1213.
Piotrek Koszuliński 7 years ago
parent
commit
75e0f8657b

+ 298 - 0
docs/builds/guides/frameworks/angular.md

@@ -0,0 +1,298 @@
+---
+category: builds-integration-frameworks
+order: 20
+---
+
+# Angular 2+ component
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-angular.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular)
+
+CKEditor 5 consists of a {@link builds/guides/overview ready to use builds} and a {@link framework/guides/overview CKEditor 5 Framework} upon which the builds are based.
+
+Currently, the CKEditor 5 component for Angular supports integrating CKEditor 5 only via builds. Integrating {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source CKEditor 5 from source} is not yet possible due to the lack of ability to [adjust webpack configuration in `angular-cli`](https://github.com/angular/angular-cli/issues/10618).
+
+<info-box>
+	While there is no support to integrate CKEditor 5 from source yet, you can still {@link builds/guides/development/custom-builds create a custom build of CKEditor 5} and include it in your Angular application.
+</info-box>
+
+## Quick start
+
+In your existing Angular project, install the [CKEditor component](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular):
+
+```bash
+npm install --save-dev @ckeditor/ckeditor5-angular
+```
+
+Install one of the {@link builds/guides/overview#available-builds official editor builds} or {@link builds/guides/development/custom-builds create a custom one} (e.g. if you want to install more plugins or customize any other thing which cannot be controlled via {@link builds/guides/integration/configuration editor configuration}.
+
+Let's say you picked [`@ckeditor/ckeditor5-build-classic`](https://www.npmjs.com/package/@ckeditor/ckeditor5-build-classic):
+
+```bash
+npm install --save-dev @ckeditor/ckeditor5-build-classic
+```
+
+**Note:** You may need to allow external JS in your project's `tsconfig.json` for the builds to work properly:
+
+```json
+"compilerOptions": {
+	"allowJs": true
+}
+```
+
+Now, add `CKEditorModule` to your application module imports:
+
+```ts
+import { CKEditorModule } from '@ckeditor/ckeditor5-angular';
+
+@NgModule( {
+	imports: [
+		...
+		CKEditorModule,
+		...
+	],
+	...
+} )
+```
+
+Import the editor build in your Angular component and assign it to a `public` property so it becomes accessible in the template:
+
+```ts
+import * as ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+
+@Component( {
+	...
+} )
+export class MyComponent {
+	public Editor = ClassicEditor;
+	...
+}
+```
+
+Finally, use the `<ckeditor>` tag in the template to run the editor:
+
+```html
+<ckeditor [editor]="Editor" data="<p>Hello world!</p>"></ckeditor>
+```
+
+Rebuild your application and CKEditor 5 should greet you with "Hello world!".
+
+### Note: Using the Document editor build
+
+If you want to use the {@link framework/guides/document-editor Document editor}, you need to {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create add the toolbar to the DOM manually}.
+
+```ts
+import * as DecoupledEditor from '@ckeditor/ckeditor5-build-decoupled-document';
+
+@Component( {
+	...
+} )
+export class MyComponent {
+	public Editor = DecoupledEditor;
+
+	public onReady( editor ) {
+		editor.ui.view.editable.element.parentElement.insertBefore(
+			editor.ui.view.toolbar.element,
+			editor.ui.view.editable.element
+		);
+	}
+}
+```
+
+```html
+<ckeditor [editor]="Editor" data="<p>Hello world!</p>" (ready)="onReady($event)"></ckeditor>
+```
+
+## Integration with `ngModel`
+
+The component implements the [`ControlValueAccessor`](https://angular.io/api/forms/ControlValueAccessor) interface and works with the `ngModel`.
+
+1. Create some model in your component to share with the editor:
+
+	```ts
+	@Component( {
+		...
+	} )
+	export class MyComponent {
+		public model = {
+			editorData: '<p>Hello world!</p>'
+		};
+		...
+	}
+	```
+
+2. Use the model in the template to enable a 2–way data binding:
+
+	```html
+	<ckeditor [(ngModel)]="model.editorData" [editor]="Editor"></ckeditor>
+	```
+
+## Supported `@Inputs`
+
+### `editor` (required)
+
+The {@link builds/guides/integration/basic-api `Editor`} which provides the static {@link module:core/editor/editor~Editor.create `create()`} method to create an instance of the editor:
+
+```html
+<ckeditor [editor]="Editor"></ckeditor>
+```
+
+### `config`
+
+The {@link module:core/editor/editorconfig~EditorConfig configuration} of the editor:
+
+```html
+<ckeditor [config]="{ toolbar: [ 'heading', '|', 'bold', 'italic' ] }" ...></ckeditor>
+```
+
+### `data`
+
+The initial data of the editor. It can be a static value:
+
+```html
+<ckeditor data="<p>Hello world!</p>" ...></ckeditor>
+```
+
+or a shared parent component's property
+
+```ts
+@Component( {
+	...
+} )
+export class MyComponent {
+	public editorData = '<p>Hello world!</p>';
+	...
+}
+```
+
+```html
+<ckeditor [data]="editorData" ...></ckeditor>
+```
+
+### `tagName`
+
+Specifies the tag name of the HTML element on which the editor will be created.
+
+The default tag is `div`.
+
+```html
+<ckeditor tagName="textarea" ...></ckeditor>
+```
+
+### `disabled`
+
+Controls the editor's {@link module:core/editor/editor~Editor#isReadOnly read–only} state:
+
+```ts
+@Component( {
+	...
+} )
+export class MyComponent {
+	public isDisabled = false;
+	...
+	toggleDisabled() {
+		this.isDisabled = !this.isDisabled
+	}
+}
+```
+
+```html
+<ckeditor [disabled]="isDisabled" ...></ckeditor>
+
+<button (click)="toggleDisabled()">
+	{{ isDisabled ? 'Enable editor' : 'Disable editor' }}
+</button>
+```
+
+## Supported `@Outputs`
+
+### `ready`
+
+Fired when the editor is ready. It corresponds with the [`editor#ready`](https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editor-Editor.html#event-ready) event. Fired with the editor instance.
+
+### `change`
+
+Fired when the content of the editor has changed. It corresponds with the {@link module:engine/model/document~Document#event:change:data `editor.model.document#change:data`} event.
+Fired with an object containing the editor and the CKEditor 5's `change:data` event object.
+
+```html
+<ckeditor [editor]="Editor" (change)="onChange($event)"></ckeditor>
+```
+
+```ts
+import * as ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+import { ChangeEvent } from '@ckeditor/ckeditor5-angular/ckeditor.component';
+
+@Component( {
+	...
+} )
+export class MyComponent {
+	public Editor = ClassicEditor;
+
+	public onChange( { editor }: ChangeEvent ) {
+		const data = editor.getData();
+
+		console.log( data );
+	}
+	...
+}
+```
+
+### `blur`
+
+Fired when the editing view of the editor is blurred. It corresponds with the {@link module:engine/view/document~Document#event:blur `editor.editing.view.document#blur`} event.
+Fired with an object containing the editor and the CKEditor 5's `blur` event data.
+
+### `focus`
+
+Fired when the editing view of the editor is focused. It corresponds with the {@link module:engine/view/document~Document#event:focus `editor.editing.view.document#focus`} event.
+Fired with an object containing the editor and the CKEditor 5's `focus` event data.
+
+## Localization
+
+CKEditor 5 can be localized in two steps.
+
+### 1. Load translation files
+
+First, you need to add translation files to the bundle. This step can be achieved in two ways:
+
+* By importing translations for given languages directly in your component file:
+
+	```ts
+	import '@ckeditor/ckeditor5-build-classic/build/translations/de';
+	import * as ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+	...
+	```
+
+* By adding paths to translation files to the `"scripts"` array in `angular.json`:
+
+	```json
+	"architect": {
+		"build": {
+			"options": {
+				"scripts": [ "node_modules/@ckeditor/ckeditor5-build-classic/build/translations/de.js" ]
+			}
+		}
+	}
+	```
+
+### 2. Configure the language
+
+Then, you need to configure the editor to use the given language:
+
+```ts
+@Component( {
+	...
+} )
+export class MyComponent {
+	public Editor = ClassicEditor;
+	public config = {
+		language: 'de'
+	};
+}
+```
+
+For advanced usage see the {@link features/ui-language Setting UI language} guide.
+
+## Contributing and reporting issues
+
+The source code of this component is available on GitHub in https://github.com/ckeditor/ckeditor5-angular.

+ 79 - 0
docs/builds/guides/frameworks/overview.md

@@ -0,0 +1,79 @@
+---
+category: builds-integration-frameworks
+order: 10
+menu-title: Overview
+---
+
+# Integrating CKEditor 5 with JavaScript frameworks
+
+## Is CKEditor 5 compatible with framework XYZ?
+
+Yes. CKEditor 5 is compatible with every JavaScript framework that we have heard of so far. CKEditor 5 is a JavaScript component (a pretty complex one but still) and does not require any uncommon techniques or technologies to be used. Threfore, unless the framework that you use has very untypical limitations, CKEditor 5 is compatible with it.
+
+> How do I use CKEditor 5 with my framework?
+
+While CKEditor 5 is compatible with your framework and initializing CKEditor 5 requires a single method call, integrating it with your framework may require using an existing or writing a new adapter (integration layer) that will communicate your framework with CKEditor 5.
+
+When checking how to integrate CKEditor 5 with your framework you can follow these steps:
+
+1. **Check whether an [official integration](#official-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+}.
+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 yourself.**
+
+	CKEditor 5 exposes a {@link builds/guides/integration/basic-api rich JavaScript API} which you can use to {@link builds/guides/integration/basic-api#creating-an-editor create} and {@link builds/guides/integration/basic-api#interacting-with-the-editor control it}.
+
+## Official integrations
+
+There are two official integrations so far:
+
+* {@link builds/guides/frameworks/react CKEditor 5 component for React}
+* {@link builds/guides/frameworks/angular CKEditor 5 component for Angular 2+}
+
+Refer to their documentation to learn how to use them.
+
+## Compatibility with Electron
+
+Starting from version 11.0.0 CKEditor 5 is compatible with Electron. Using CKEditor 5 in Electron applications do not require any additional steps.
+
+Check out a [sweet screencast of CKEditor 5 with real-time collaboration in Electron](https://twitter.com/ckeditor/status/1016627687568363520).
+
+## Compatibility with Bootstrap
+
+In order to display CKEditor 5 inside [Bootstrap](https://getbootstrap.com/) modals you need to configure two things:
+
+* The `z-index` of CKEditor 5's floating balloons so they are displayed above the Bootstrap's overlay.
+* Configure Bootstrap to not steal focus from CKEditor 5 fields.
+
+The above can be ensured by adding this CSS:
+
+```css
+/*
+	We need to add this CSS custom property to the body instead of :root,
+	because of CSS specificity.
+*/
+body {
+	--ck-z-default: 100;
+	--ck-z-modal: calc( var(--ck-z-default) + 999 );
+}
+
+/*
+	Override Bootstrap's CSS.
+	Note: this won't be necessary once the following issue is fixed and released:
+	https://github.com/ckeditor/ckeditor5-theme-lark/issues/189
+*/
+.ck.ck-button {
+	-webkit-appearance: none;
+}
+```
+
+And passing the `focus: false` option to Boostrap's `modal()` function:
+
+```js
+$( '#modal-container' ).modal( {
+	focus: false
+} );
+```
+
+Check out the demo on https://codepen.io/ckeditor/pen/vzvgOe.

+ 362 - 0
docs/builds/guides/frameworks/react.md

@@ -0,0 +1,362 @@
+---
+category: builds-integration-frameworks
+order: 30
+---
+
+# React component
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-react.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-react)
+
+CKEditor 5 consists of a {@link builds/guides/overview ready to use builds} and a {@link framework/guides/overview CKEditor 5 Framework} upon which the builds are based.
+
+The easiest way to use CKEditor 5 in your React application is by choosing one of the {@link builds/guides/overview#available-builds editor builds}. Additionally, it is also possible to integrate into your application [CKEditor 5 from source](#integrating-ckeditor-5-from-source).
+
+## Quick start
+
+Install the component and the build of your choice:
+
+```bash
+npm install --save @ckeditor/ckeditor5-react @ckeditor/ckeditor5-build-classic
+```
+
+Use the `<CKEditor>` component inside your project:
+
+```jsx
+import React, { Component } from 'react';
+import CKEditor from '@ckeditor/ckeditor5-react';
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+
+class App extends Component {
+    render() {
+        return (
+            <div className="App">
+                <h2>Using CKEditor 5 build in React</h2>
+                <CKEditor
+                    editor={ ClassicEditor }
+                    data="<p>Hello from CKEditor 5!</p>"
+                    onInit={ editor => {
+                        // You can store the "editor" and use when it's needed.
+                        console.log( 'Editor is ready to use!', editor );
+                    } }
+                    onChange={ ( event, editor ) => {
+                        const data = editor.getData();
+                        console.log( { event, editor, data } );
+                    } }
+                />
+            </div>
+        );
+    }
+}
+
+export default App;
+```
+
+### Component properties
+
+The `<CKEditor>` component supports the following properties:
+
+* `editor` (required) &ndash; The {@link module:core/editor/editor~Editor `Editor`} constructor to use.
+* `data` &ndash; The initial data for the created editor. See the {@link builds/guides/integration/basic-api#interacting-with-the-editor Basic API} guide.
+* `config` &ndash; The editor configuration. See the {@link builds/guides/integration/configuration Configuration} guide.
+* `onChange` &ndash; A function called when the editor's data changed. See the {@link module:engine/model/document~Document#event:change:data `editor.model.document#change:data`} event.
+
+	The callback receives two parameters:
+
+	1. an {@link module:utils/eventinfo~EventInfo `EventInfo`} object,
+	2. an {@link module:core/editor/editor~Editor `Editor`} instance.
+* `onInit` &ndash; A function called when the editor was initialized. It receives the initialized {@link module:core/editor/editor~Editor `editor`} as a parameter.
+
+### Customizing the builds
+
+{@link builds/guides/overview CKEditor 5 builds} come ready to use, with a set of built-in plugins and a predefined configuration. While you can change the configuration easily by using the `config` property of the `<CKEditor>` component which allows you to change the {@link builds/guides/integration/configuration#toolbar-setup toolbar} or {@link builds/guides/integration/configuration#removing-features remove some plugins}, in order to add plugins you need to rebuild the editor.
+
+There are two main ways to do that.
+
+* {@link builds/guides/development/custom-builds Customize one of the existing builds}.
+
+	This option does not require any changes in your project's configuration. You will create a new build somewhere next to your project and include it like you included one of the existing builds. Therefore, it is the easiest way to add missing features. Read more about this method in {@link builds/guides/integration/installing-plugins Installing plugins}.
+* {@link builds/guides/integration/advanced-setup Integrate the editor from source}.
+
+	In this approach you will include CKEditor 5 from source &mdash; so you will choose the editor creator you want and the list of plugins, etc. It is more powerful and creates a tighter integration between your application and CKEditor 5, however, it requires adjusting your `webpack.config.js` to CKEditor 5 needs.
+
+	Read more about this option in [Integrating CKEditor 5 from source](#integrating-ckeditor-5-from-source).
+
+### Note: Building for production
+
+If you use `create-react-app` or use a custom configuration for you application but still use `webpack@3`, you will need to adjust the `UglifyJsPlugin` options to make CKEditor 5 compatible with this setup. CKEditor 5 builds use ES6 so the default JavaScript minifier of `webpack@3` and `create-react-app` is not able to digest them.
+
+To do that, you need to first [eject the configuration](https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#npm-run-eject) from the setup created via `create-react-app` (assuming that you use it).
+
+```bash
+npm run eject
+```
+
+Then, you can customize `UglifyJsPlugin` options in the webpack configuration. Read how to do this [here](#changes-required-in-webpacks-production-config).
+
+**Note**: The latest `webpack@4` comes with a version of `UglifyJsPlugin` which supports ES6 out of the box. Also, the React community works on allowing importing ES6 libraries into your applications, so this step will soon be no longer required.
+
+### Note: Using the document editor build
+
+If you use the {@link framework/guides/document-editor Document editor}, {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create you need to add the toolbar to the DOM manually}:
+
+```jsx
+import DecoupledEditor from '@ckeditor/ckeditor5-build-decoupled-document';
+
+class App extends Component {
+    render() {
+        return (
+            <div className="App">
+                <h2>CKEditor 5 using a custom build - DecoupledEditor</h2>
+                <CKEditor
+                    onInit={ editor => {
+                        console.log( 'Editor is ready to use!', editor );
+
+                        // Insert the toolbar before the editable area.
+                        editor.ui.view.editable.element.parentElement.insertBefore(
+                            editor.ui.view.toolbar.element,
+                            editor.ui.view.editable.element
+                        );
+                    } }
+                    onChange={ ( event, editor ) => console.log( { event, editor } ) }
+                    editor={ DecoupledEditor }
+                    data="<p>Hello from CKEditor 5's DecoupledEditor!</p>"
+                    config={ /* the editor configuration */ }
+                />
+        );
+    }
+}
+
+export default App;
+```
+
+## Integrating CKEditor 5 from source
+
+Integrating the 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 [Create React App CLI](https://github.com/facebook/create-react-app) as your boilerplate and it goes through adjusting it to fit CKEditor 5's needs. If you use your custom webpack setup, please read more about {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source including CKEditor 5 from source}.
+
+Install React CLI:
+
+```bash
+npm install -g create-react-app
+```
+
+Create your project using the CLI and go to the project's directory:
+
+```bash
+create-react-app ckeditor5-react-example && cd ckeditor5-react-example
+```
+
+Now, you can eject the configuration:
+
+```bash
+npm run eject
+```
+
+You need to eject the configuration in order to be able to customize webpack configuration. In order to build CKEditor 5 from source you need to load inline SVG images and handle CKEditor 5's CSS as well as correctly minify ES6 source.
+
+<info-box>
+	You can find more information about ejecting [here](https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#npm-run-eject).
+</info-box>
+
+### Changes required in webpack's production config
+
+At this stage, if you would try to build your application with CKEditor 5's source included, you would get the following error:
+
+```bash
+Failed to minify the code from this file:                                              [31/75]
+        <project_root>/node_modules/@ckeditor/ckeditor5-build-classic/build/ckeditor.js:5:2077
+```
+
+UglifyJS exported by `webpack@3` cannot parse code written in ES6. You need to manually replace it with `uglifyjs-webpack-plugin`. **These changes touch the `webpack.config.prod.js` file only.**
+
+After ejecting, this file is placed in `<project_root>/config/webpack.config.prod.js`. You need to make the following changes:
+
+1. Install `uglifyjs-webpack-plugin`:
+
+	```bash
+	npm install --save-dev uglifyjs-webpack-plugin
+	```
+
+2. Load the installed package (at the top of the `webpack.config.prod.js` file):
+
+	```js
+	const UglifyJsWebpackPlugin = require( 'uglifyjs-webpack-plugin' );
+	```
+
+3. Replace the `webpack.optimize.UglifyJsPlugin` with `UglifyJsWebpackPlugin`:
+
+	```diff
+	- new webpack.optimize.UglifyJsPlugin
+	+ new UglifyJsWebpackPlugin
+	```
+
+4. Options: `compress`, `mangle` and `output` cannot be passed directly to `UglifyJsWebpackPlugin`. You need to wrap these options in `uglifyOptions: { ... }`.
+
+In the end, the entire plugin definition should look as follows:
+
+```js
+// Minify the code.
+new UglifyJsWebpackPlugin( {
+  uglifyOptions: {
+    compress: {
+      warnings: false,
+      // Disabled because of an issue with Uglify breaking seemingly valid code:
+      // https://github.com/facebookincubator/create-react-app/issues/2376
+      // Pending further investigation:
+      // https://github.com/mishoo/UglifyJS2/issues/2011
+      comparisons: false,
+    },
+    mangle: {
+        safari10: true,
+    },
+    output: {
+        comments: false,
+        // Turned on because emoji and regex is not minified properly using default
+        // https://github.com/facebookincubator/create-react-app/issues/2488
+        ascii_only: true,
+    },
+  },
+  sourceMap: shouldUseSourceMap,
+} )
+```
+
+### Changes required in both webpack configs
+
+In order to build your application properly, you need to modify your webpack configuration files. After ejecting they are located at:
+
+```bash
+<project_root>/config/webpack.config.dev.js
+<project_root>/config/webpack.config.prod.js
+```
+
+You need to modify the webpack configuration to load CKEditor 5 SVG icons properly.
+
+At the beginning import an object that creates the configuration for PostCSS:
+
+```js
+const { styles } = require( '@ckeditor/ckeditor5-dev-utils' );
+```
+
+Then add two new elements to the exported object under the `module.rules` array (as new items for the `oneOf` array). These are SVG and CSS loaders only for CKEditor 5 code:
+
+```js
+{
+  test: /ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/,
+  use: [ 'raw-loader' ]
+},
+{
+  test: /ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css/,
+  use: [
+    {
+      loader: 'style-loader',
+      options: {
+        singleton: true
+      }
+    },
+    {
+      loader: 'postcss-loader',
+      options: styles.getPostCssConfig( {
+        themeImporter: {
+          themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
+        },
+        minify: true
+      } )
+    }
+  ]
+},
+```
+
+Exclude CSS files used by CKEditor 5 from project's CSS loader:
+
+```js
+{
+  test: /\.css$/,
+  exclude: /ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css/,
+  // (...)
+}
+```
+
+And exclude CKEditor 5 SVG and CSS files from `file-loader` because these files will be handled by the loaders added previously (usually the last item in the `module.rules` array is the `file-loader`) so it looks like this:
+
+```js
+{
+  loader: require.resolve('file-loader'),
+  // Exclude `js` files to keep the "css" loader working as it injects
+  // its runtime that would otherwise be processed through the "file" loader.
+  // Also exclude `html` and `json` extensions so they get processed
+  // by webpack's internal loaders.
+  exclude: [
+    /\.(js|jsx|mjs)$/,
+    /\.html$/,
+    /\.json$/,
+    /ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/,
+    /ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css/
+  ],
+  options: {
+    name: 'static/media/[name].[hash:8].[ext]'
+  }
+}
+```
+
+**Remember that the changes above should be done in both configuration files.**
+
+Next, install `raw-loader`, the theme for CKEditor 5 and CKEditor 5 development utilities:
+
+```bash
+npm install --save-dev raw-loader @ckeditor/ckeditor5-theme-lark @ckeditor/ckeditor5-dev-utils
+```
+
+Finally, install the component, the specific editor and plugins you want to use:
+
+```bash
+npm install --save \
+	@ckeditor/ckeditor5-react \
+	@ckeditor/ckeditor5-editor-classic \
+	@ckeditor/ckeditor5-essentials \
+	@ckeditor/ckeditor5-basic-styles \
+	@ckeditor/ckeditor5-heading \
+	@ckeditor/ckeditor5-paragraph
+```
+
+### Using CKEditor 5 source
+
+Now you can use CKEditor component together with {@link framework/guides/overview CKEditor 5 Framework}:
+
+```jsx
+import React, { Component } from 'react';
+import CKEditor from '@ckeditor/ckeditor5-react';
+
+import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
+import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
+import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
+import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
+import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
+import Heading from '@ckeditor/ckeditor5-heading/src/heading';
+
+class App extends Component {
+    render() {
+        return (
+            <div className="App">
+                <h2>Using CKEditor 5 Framework in React</h2>
+                <CKEditor
+                    onInit={ editor => console.log( 'Editor is ready to use!', editor ) }
+                    onChange={ ( event, editor ) => console.log( { event, editor } ) }
+                    config={ {
+                        plugins: [ Essentials, Paragraph, Bold, Italic, Heading ],
+                        toolbar: [ 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo', ]
+                    } }
+                    editor={ ClassicEditor }
+                    data="<p>Hello from CKEditor 5!</p>"
+                />
+            </div>
+        );
+    }
+}
+
+export default App;
+```
+
+## Contributing and reporting issues
+
+The source code of this component is available on GitHub in https://github.com/ckeditor/ckeditor5-react.

+ 10 - 0
docs/builds/guides/integration/basic-api.md

@@ -166,6 +166,16 @@ editor.destroy()
 
 Once destroyed, resources used by the editor instance are released and the original element used to create the editor is automatically displayed and updated to reflect the final editor data.
 
+### Listening to changes
+
+{@link module:engine/model/document~Document#change:data `Document#change:data`}.
+
+editor.model.document.on( 'change:data', () => {
+    console.log( 'The data has changed!' );
+} );
+
+This event is fired when the document changes in such a way which is "visible" in the editor data. There is also a group of changes, like selection position changes, marker changes which do not affect the result of `editor.getData()`. To listen to all these changes, you can use a wider {@link module:engine/model/document~Document#change `Document#change`} event.
+
 ## UMD support
 
 Because builds are distributed as [UMD modules](https://github.com/umdjs/umd), editor classes can be retrieved in various ways:

+ 9 - 1
docs/umberto.json

@@ -70,7 +70,15 @@
 							"name": "Integration",
 							"id": "builds-integration",
 							"slug": "integration",
-							"order": 100
+							"order": 100,
+							"categories": [
+								{
+									"name": "Frameworks",
+									"id": "builds-integration-frameworks",
+									"slug": "frameworks",
+									"order": 100
+								}
+							]
 						},
 						{
 							"name": "Development",