Skip to content

Commit

Permalink
Docs: Updated docs after simplifying builds structure. Closes #1038.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Reinmar
Reinmar committed Jul 17, 2018
1 parent 57f5291 commit 6611430
Show file tree
Hide file tree
Showing 2 changed files with 141 additions and 124 deletions.
94 changes: 46 additions & 48 deletions docs/builds/guides/development/custom-builds.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Some of the reasons for creating custom builds are:

* Adding features which are not included in the existing builds, either from a third party or custom developed.
* Removing unnecessary features present in a build.
* Changing the {@link builds/guides/integration/basic-api#creators editor creator}.
* Changing the {@link builds/guides/integration/basic-api#creating-an-editor editor creator}.
* Changing the {@link framework/guides/theme-customization editor theme}.
* Changing the {@link features/ui-language localization language} of the editor.
* Enabling bug fixes which are still not a part of any public release.
Expand Down Expand Up @@ -46,7 +46,7 @@ git remote add upstream https://github.com/ckeditor/ckeditor5-build-classic.git
<info-box hint>
If you do not want to fork the official build, you can just clone it. However, you will not be able to commit and push your customizations back to GitHub.

Alternatively, instead of creating a custom build you can {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source integrate CKEditor 5 directly from source}. This option allows even greater flexibility and requires less overhead (you will not need to fork the official build).
Alternatively, instead of creating a custom build you can {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source integrate CKEditor 5 directly from source}. This option allows even greater flexibility and requires less overhead (you will not need to fork the official build). However, it requires that you fully control the `webpack.config.js` file (which is not that easy in some environments – e.g. in [`angular-cli`](https://cli.angular.io/) or [`create-react-app`](https://github.com/facebook/create-react-app)).
</info-box>

<info-box warning>
Expand All @@ -58,17 +58,16 @@ git remote add upstream https://github.com/ckeditor/ckeditor5-build-classic.git
Every build contains the following files:

* `build/ckeditor.js` &ndash; The ready-to-use editor bundle, containing the editor and all plugins.
* `src/ckeditor.js` &ndash; The source entry point of the build. It can be used for complex bundling and development. Based on it the `build/ckeditor.js` file is created by [webpack](https://webpack.js.org).
* `build-config.js` &ndash; The configuration of this particular CKEditor 5 build, based on which the `src/ckeditor.js` file is created.
* `src/ckeditor.js` &ndash; The source entry point of the build. Based on it the `build/ckeditor.js` file is created by [webpack](https://webpack.js.org). It defines the editor creator, a list of plugins and the default config of a build.
* `webpack-config.js` &ndash; webpack configuration used to build the editor.

## Customizing a build

In order to customize a build you need to:

* Install missing dependencies.
* Update the `build-config.js` file.
* Update the builds (which includes updating `src/ckeditor.js` and the editor bundle in `build/`).
* Update the `src/ckeditor.js` file.
* Update the build (the editor bundle in `build/`).

### Installing dependencies

Expand All @@ -94,64 +93,63 @@ This will install the package and add it to `package.json`. You can also edit `p

### Updating build configuration

If you added or removed dependencies, you will also need to modify the `build-config.js` file. Based on it the bundler entry file (`src/ckeditor.js`) will be created. You can also opt out from automatically creating the entry file and modify `src/ckeditor.js` manually, which can be useful in some non-standard cases.
If you added or removed dependencies, you will also need to modify the `src/ckeditor.js` file.

Either way, every plugin that you want to include in the bundle should be included at this stage. You can also change the editor creator and specify the default editor configuration. For instance, your build configuration might look like this:
Every plugin that you want to include in the bundle should be included at this stage. You can also change the editor creator and specify the default editor configuration. For instance, your webpack entry file (`src/ckeditor.js`) may look like this:

```js
'use strict';

module.exports = {
// The editor creator to use.
editor: '@ckeditor/ckeditor5-editor-classic/src/classiceditor',

// The name under which the editor will be exported.
moduleName: 'ClassicEditor',

// Plugins to include in the build.
plugins: [
'@ckeditor/ckeditor5-essentials/src/essentials',

'@ckeditor/ckeditor5-autoformat/src/autoformat',
'@ckeditor/ckeditor5-basic-styles/src/bold',
'@ckeditor/ckeditor5-basic-styles/src/italic',
'@ckeditor/ckeditor5-heading/src/heading',
'@ckeditor/ckeditor5-link/src/link',
'@ckeditor/ckeditor5-list/src/list',
'@ckeditor/ckeditor5-paragraph/src/paragraph',

'ckeditor5-custom-package/src/customplugin',
'../relative/path/to/some/othercustomplugin'
],

// Editor configuration.
config: {
toolbar: [ 'heading', '|', 'bold', 'italic', 'custombutton' ],

// UI language. Language codes follow the https://en.wikipedia.org/wiki/ISO_639-1 format.
language: 'en'
}
// The editor creator to use.
import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

import EssentialsPlugin from '@ckeditor/ckeditor5-essentials/src/essentials';
import AutoformatPlugin from '@ckeditor/ckeditor5-autoformat/src/autoformat';
import BoldPlugin from '@ckeditor/ckeditor5-basic-styles/src/bold';
import ItalicPlugin from '@ckeditor/ckeditor5-basic-styles/src/italic';
import HeadingPlugin from '@ckeditor/ckeditor5-heading/src/heading';
import LinkPlugin from '@ckeditor/ckeditor5-link/src/link';
import ListPlugin from '@ckeditor/ckeditor5-list/src/list';
import ParagraphPlugin from '@ckeditor/ckeditor5-paragraph/src/paragraph';

import CustomPlugin from 'ckeditor5-custom-package/src/customplugin';
import OtherCustomPlugin from '../relative/path/to/some/othercustomplugin';

export default class ClassicEditor extends ClassicEditorBase {}

// Plugins to include in the build.
ClassicEditor.builtinPlugins = [
EssentialsPlugin,
AutoformatPlugin,
BoldPlugin,
ItalicPlugin,
HeadingPlugin,
LinkPlugin,
ListPlugin,
ParagraphPlugin,

CustomPlugin,
OtherCustomPlugin
];

ClassicEditor.defaultConfig = {
toolbar: [ 'heading', '|', 'bold', 'italic', 'custombutton' ],

// This value must be kept in sync with the language defined in webpack.config.js.
language: 'en'
};
```

### Rebuilding the bundle

After you changed the build configuration or updated some dependencies, it is time to rebuild the bundle. This will run a bundler (webpack) with a proper configuration (see `webpack.config.js`).
After you changed the webpack entry file or updated some dependencies, it is time to rebuild the bundle. This will run a bundler (webpack) with a proper configuration (see `webpack.config.js`).

If you wish to create a bundle based on the build configuration (`build-config.js`), run:
To do that, execute the following command:

```bash
npm run build
```

This command will update the entry file (`src/ckeditor.js`) and create the bundle &mdash; `build/ckeditor.js`.

If you want to skip updating the entry file (in case you modified it manually), run:

```bash
npm run build-ckeditor
```

You can validate whether your new build works by opening the `sample/index.html` file in a browser (via HTTP, not as a local file). Make sure to **clear the cache**.

## Updating the build
Expand Down
171 changes: 95 additions & 76 deletions docs/builds/guides/integration/installing-plugins.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,63 +41,82 @@ Now, install the plugin package:
npm install --save-dev @ckeditor/ckeditor5-alignment
```

Edit the `build-config.js` file to add your plugin to the list of plugins which will be included in the build and to add your feature's button to the toolbar:
Edit the `src/ckeditor.js` file to add your plugin to the list of plugins which will be included in the build and to add your feature's button to the toolbar:

```
module.exports = {
// The editor creator to use.
editor: '@ckeditor/ckeditor5-editor-classic/src/classiceditor',
// The name under which the editor will be exported.
moduleName: 'ClassicEditor',
// Plugins to include in the build.
plugins: [
'@ckeditor/ckeditor5-essentials/src/essentials',
'@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter',
'@ckeditor/ckeditor5-autoformat/src/autoformat',
'@ckeditor/ckeditor5-basic-styles/src/bold',
'@ckeditor/ckeditor5-basic-styles/src/italic',
'@ckeditor/ckeditor5-block-quote/src/blockquote',
'@ckeditor/ckeditor5-easy-image/src/easyimage',
'@ckeditor/ckeditor5-heading/src/heading',
'@ckeditor/ckeditor5-image/src/image',
'@ckeditor/ckeditor5-image/src/imagecaption',
'@ckeditor/ckeditor5-image/src/imagestyle',
'@ckeditor/ckeditor5-image/src/imagetoolbar',
'@ckeditor/ckeditor5-link/src/link',
'@ckeditor/ckeditor5-list/src/list',
'@ckeditor/ckeditor5-paragraph/src/paragraph',
'@ckeditor/ckeditor5-upload/src/imageupload',
'@ckeditor/ckeditor5-alignment/src/alignment', // <--- ADDED
],
// Editor config.
config: {
toolbar: {
items: [
'heading',
'alignment', // <--- ADDED
'bold',
'italic',
'link',
'bulletedList',
'numberedList',
'blockQuote',
'undo',
'redo'
]
},
image: {
toolbar: [ 'imageStyle:full', 'imageStyle:side', '|', 'imageTextAlternative' ]
},
// UI language. Language codes follow the https://en.wikipedia.org/wiki/ISO_639-1 format.
language: 'en'
}
```js
// The editor creator to use.
import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import UploadAdapter from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
import Autoformat from '@ckeditor/ckeditor5-autoformat/src/autoformat';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import BlockQuote from '@ckeditor/ckeditor5-block-quote/src/blockquote';
import EasyImage from '@ckeditor/ckeditor5-easy-image/src/easyimage';
import Heading from '@ckeditor/ckeditor5-heading/src/heading';
import Image from '@ckeditor/ckeditor5-image/src/image';
import ImageCaption from '@ckeditor/ckeditor5-image/src/imagecaption';
import ImageStyle from '@ckeditor/ckeditor5-image/src/imagestyle';
import ImageToolbar from '@ckeditor/ckeditor5-image/src/imagetoolbar';
import ImageUpload from '@ckeditor/ckeditor5-image/src/imageupload';
import Link from '@ckeditor/ckeditor5-link/src/link';
import List from '@ckeditor/ckeditor5-list/src/list';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';

import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment'; // <--- ADDED

export default class ClassicEditor extends ClassicEditorBase {}

// Plugins to include in the build.
ClassicEditor.builtinPlugins = [
Essentials,
UploadAdapter,
Autoformat,
Bold,
Italic,
BlockQuote,
EasyImage,
Heading,
Image,
ImageCaption,
ImageStyle,
ImageToolbar,
ImageUpload,
Link,
List,
Paragraph,
Alignment // <--- ADDED
];

// Editor configuration.
ClassicEditor.defaultConfig = {
toolbar: {
items: [
'heading',
'|',
'alignment', // <--- ADDED
'bold',
'italic',
'link',
'bulletedList',
'numberedList',
'imageUpload',
'blockQuote',
'undo',
'redo'
]
},
image: {
toolbar: [
'imageStyle:full',
'imageStyle:side',
'|',
'imageTextAlternative'
]
},
// This value must be kept in sync with the language defined in webpack.config.js.
language: 'en'
};
```

Expand Down Expand Up @@ -136,12 +155,12 @@ 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 Alignment from '@ckeditor/ckeditor5-alignment/src/alignment'; // <--- ADDED
import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment'; // <--- ADDED

ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ Essentials, Paragraph, Bold, Italic, Alignment ], // <--- MODIFIED
toolbar: [ 'bold', 'italic', 'alignment' ] // <--- MODIFIED
plugins: [ Essentials, Paragraph, Bold, Italic, Alignment ], // <--- MODIFIED
toolbar: [ 'bold', 'italic', 'alignment' ] // <--- MODIFIED
} )
.then( editor => {
console.log( 'Editor was initialized', editor );
Expand Down Expand Up @@ -181,27 +200,27 @@ ClassicEditor
} );
```

All this works because a typical `src/ckeditor.js` module that you can find in every editor build repository (see e.g. [`@ckeditor/ckeditor5-build-classic`](https://github.com/ckeditor/ckeditor5-build-classic/blob/stable/src/ckeditor.js)), which is created based on the `build-config.js` file and based on which a build is created, looks like this:
All this works because a typical `src/ckeditor.js` module that you can find in every editor build repository (see e.g. [`@ckeditor/ckeditor5-build-classic`](https://github.com/ckeditor/ckeditor5-build-classic/blob/stable/src/ckeditor.js)) looks like this:

```js
import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
import EssentialsPlugin from '@ckeditor/ckeditor5-essentials/src/essentials';
import UploadAdapterPlugin from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
import AutoformatPlugin from '@ckeditor/ckeditor5-autoformat/src/autoformat';
import BoldPlugin from '@ckeditor/ckeditor5-basic-styles/src/bold';
import ItalicPlugin from '@ckeditor/ckeditor5-basic-styles/src/italic';
import BlockQuotePlugin from '@ckeditor/ckeditor5-block-quote/src/blockquote';
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import UploadAdapter from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
import Autoformat from '@ckeditor/ckeditor5-autoformat/src/autoformat';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import BlockQuote from '@ckeditor/ckeditor5-block-quote/src/blockquote';
// ...

export default class ClassicEditor extends ClassicEditorBase {}

ClassicEditor.builtInPlugins = [
EssentialsPlugin,
UploadAdapterPlugin,
AutoformatPlugin,
BoldPlugin,
ItalicPlugin,
BlockQuotePlugin,
ClassicEditor.builtinPlugins = [
Essentials,
UploadAdapter,
Autoformat,
Bold,
Italic,
BlockQuote,
// ...
];

Expand All @@ -217,15 +236,15 @@ ClassicEditor.defaultConfig = {
};
```

This code imports the source of the classic editor and extends it with a static property `build` in which it defines a set of plugins and configuration to be used by this editor class.
This code imports the source of the classic editor and extends it with a static `builtinPlugins` and `defaultConfig` properties in which it defines a set of plugins and configuration to be used by this editor class.

In this approach, all editor instances created by using this editor build will by default load all these built-in plugins and configuration.

<info-box>
You can still use the {@link module:core/editor/editorconfig~EditorConfig#removePlugins `config.removePlugins`} and {@link module:core/editor/editorconfig~EditorConfig#plugins `config.plugins`} options to override the default configuration.
</info-box>

When building the editor from source and not using a build as a base, you can also use the static `build` property of editor classes. However, in this situation it is usually more convenient to simply pass all the plugins directly to the static `create()` method:
When building the editor from source and not using a build as a base, you can also use the static `builtinPlugins` and `defaultConfig` properties of editor classes. However, in this situation it is usually more convenient to simply pass all the plugins directly to the static `create()` method:

```js
import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
Expand All @@ -247,4 +266,4 @@ ClassicEditor
} );
```

So, in short, both methods use very similar mechanisms. However, adding a plugin through the static `build` property (which happens in editor builds) lets you automatically enable it in all editor instances created using this editor class, while passing a plugin to `create()` will naturally affect only one instance.
So, in short, both methods use very similar mechanisms. However, adding a plugin through the static `builtinPlugins` property (which happens in editor builds) lets you automatically enable it in all editor instances created using this editor class, while passing a plugin to `create()` will naturally affect only one instance.

0 comments on commit 6611430

Please sign in to comment.