Explorar o código

Docs: Documented how to create super builds. Closes #923.

Piotrek Koszuliński %!s(int64=7) %!d(string=hai) anos
pai
achega
a6f4f9db96

+ 1 - 1
docs/builds/guides/development/custom-builds.md

@@ -34,7 +34,7 @@ In order to start developing CKEditor 5 you will require:
 Start with [forking](https://help.github.com/articles/fork-a-repo/) one of the official builds (it will serve as the starting point for your custom one) and then clone your fork:
 
 ```bash
-git clone -b stable https://github.com/<your-username>/ckeditor5-build-classic.git
+git clone -b stable git@github.com:<your-username>/ckeditor5-build-classic.git
 ```
 
 To make updating easier you may optionally add the original build repository to your Git remotes:

+ 163 - 0
docs/builds/guides/integration/advanced-setup.md

@@ -449,3 +449,166 @@ entry: [
 <info-box>
 	The [`babel-preset-env`](https://github.com/babel/babel-preset-env) package lets you choose the environment that you want to support and transpiles ES6+ features to match that environment's capabilities. Without configuration it will produce ES5 builds.
 </info-box>
+
+## Scenario 3: Using two different editors
+
+A common requirement is the ability to use two or more types of editors on one page. For instance, you may want to use the {@link builds/guides/overview#classic-editor classic editor} next to a couple of {@link builds/guides/overview#inline-editor inline editors}.
+
+**Do not load two builds on one page.** This is a mistake which leads to:
+
+* Code duplication. Both builds share up to 99% of the code, including CSS and SVGs. By loading them twice you make your page unnecessarily heavy.
+* Duplicated CSS may lead to conflicts and, thus, broken UI of the editors.
+* Translation repository gets duplicated entries which may cause loading incorrect strings with translations.
+
+### Solutions
+
+If you want to load two different editors on one page you need to make sure that they are build together (once). This can be achieved in at least two ways:
+
+* [Integrating CKEditor 5 from source](#running-the-editor-method-2) directly into your application. Since you build you application once the editors that you will use will be built together too.
+* [Creating a "super build" of CKEditor 5](#creating-super-builds). Instead of creating a build which exports just one editor, you can create a build which exports two or more at the same time.
+
+### Creating "super builds"
+
+There is no limit for how many editor classes can a single build export. By default, the official builds export a single editor class only. However, they can easily import more.
+
+You can start from forking (or copying) an existing build like in the {@link builds/guides/development/custom-builds "Creating custom builds"} guide. Let's say you forked and cloned the [`ckeditor5-build-classic`](http://github.com/ckeditor/ckeditor5-build-classic) repository and want to add {@link module:editor-inline/inlineeditor~InlineEditor} to it:
+
+```bash
+git clone -b stable git@github.com:<your-username>/ckeditor5-build-classic.git
+cd ckeditor5-build-classic
+npm install
+```
+
+Now, it is time to add the missing editor package and install:
+
+```
+npm install --save-dev @ckeditor/ckeditor5-editor-inline
+```
+
+Once all the dependencies are installed, let's modify the webpack's entry point which is the `src/ckeditor.js` file. For now it was exporting just a single class:
+
+```js
+// The editor creator to use.
+import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
+
+// ...
+
+export default class ClassicEditor extends ClassicEditorBase {}
+
+// Plugins to include in the build.
+ClassicEditor.builtinPlugins = [
+	// ...
+];
+
+// Editor configuration.
+ClassicEditor.defaultConfig = {
+	// ...
+};
+```
+
+Let's make it export an object with two classes – `ClassicEditor` and `InlineEditor`. To make both constructors work in the same way (load the same plugins and default configuration) we also need to assign `builtinPlugins` and `defaultConfig` static properties to both of them:
+
+```js
+// The editor creators to use.
+import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
+import InlineEditorBase from '@ckeditor/ckeditor5-editor-inline/src/inlineeditor';
+
+// ...
+
+class ClassicEditor extends ClassicEditorBase {}
+class InlineEditor extends InlineEditorBase {}
+
+// Plugins to include in the build.
+const plugins = [
+	// ...
+];
+
+ClassicEditor.builtinPlugins = plugins;
+InlineEditor.builtinPlugins = plugins;
+
+// Editor configuration.
+const config = {
+	// ...
+};
+
+ClassicEditor.defaultConfig = config;
+InlineEditor.defaultConfig = config;
+
+export default {
+	ClassicEditor, InlineEditor
+};
+```
+
+Since now we export an object with two properties `ClassicEditor` and `InlineEditor` it is also reasonable to rename the global variable to which webpack will assign this object. So far it was called `ClassicEditor`. A more adequate name now would be for example `CKEDITOR`. This variable is defined in `webpack.config.js` in the `output.library` setting:
+
+```diff
+diff --git a/webpack.config.js b/webpack.config.js
+index c57e371..04fc9fe 100644
+--- a/webpack.config.js
++++ b/webpack.config.js
+@@ -21,7 +21,7 @@ module.exports = {
+
+     output: {
+         // The name under which the editor will be exported.
+-        library: 'ClassicEditor',
++        library: 'CKEDITOR',
+
+         path: path.resolve( __dirname, 'build' ),
+         filename: 'ckeditor.js',
+```
+
+Once you changed the `src/ckeditor.js` and `webpack.config.js` files it is time to rebuild the build:
+
+```bash
+npm run build
+```
+
+Finally, webpack finishes compiling your super build, you can change the `samples/index.html` file to test both editors:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<title>CKEditor 5 – super build</title>
+	<style>
+		body {
+			max-width: 800px;
+			margin: 20px auto;
+		}
+	</style>
+</head>
+<body>
+
+<h1>CKEditor 5 – super build</h1>
+
+<div id="classic-editor">
+	<h2>Sample</h2>
+
+	<p>This is an instance of the <a href="https://ckeditor.com/docs/ckeditor5/latest/builds/guides/overview.html#classic-editor">classic editor build</a>.</p>
+</div>
+
+<div id="inline-editor">
+	<h2>Sample</h2>
+
+	<p>This is an instance of the <a href="https://ckeditor.com/docs/ckeditor5/latest/builds/guides/overview.html#inline-editor">inline editor build</a>.</p>
+</div>
+
+<script src="../build/ckeditor.js"></script>
+<script>
+	CKEDITOR.ClassicEditor
+		.create( document.querySelector( '#classic-editor' ) )
+		.catch( err => {
+			console.error( err.stack );
+		} );
+
+	CKEDITOR.InlineEditor
+		.create( document.querySelector( '#inline-editor' ) )
+		.catch( err => {
+			console.error( err.stack );
+		} );
+</script>
+
+</body>
+</html>
+```