瀏覽代碼

Merge branch 'master' into t/645

Aleksander Nowodzinski 8 年之前
父節點
當前提交
362d8d21b5

+ 4 - 1
README.md

@@ -1,12 +1,15 @@
 CKEditor 5 [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Check%20out%20CKEditor%205%20on%20GitHub%20&url=https://github.com/ckeditor/ckeditor5)
 ===================================
 
-[![Join the chat at https://gitter.im/ckeditor/ckeditor5](https://badges.gitter.im/ckeditor/ckeditor5.svg)](https://gitter.im/ckeditor/ckeditor5?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![Build Status](https://travis-ci.org/ckeditor/ckeditor5.svg?branch=master)](https://travis-ci.org/ckeditor/ckeditor5)
 [![BrowserStack Status](https://www.browserstack.com/automate/badge.svg?badge_key=d3hvenZqQVZERFQ5d09FWXdyT0ozVXhLaVltRFRjTTUyZGpvQWNmWVhUUT0tLUZqNlJ1YWRUd0RvdEVOaEptM1B2Q0E9PQ==--c9d3dee40b9b4471ff3fb516d9ecf8d09292c7e0)](https://www.browserstack.com/automate/public-build/d3hvenZqQVZERFQ5d09FWXdyT0ozVXhLaVltRFRjTTUyZGpvQWNmWVhUUT0tLUZqNlJ1YWRUd0RvdEVOaEptM1B2Q0E9PQ==--c9d3dee40b9b4471ff3fb516d9ecf8d09292c7e0)
 [![Dependency Status](https://img.shields.io/david/ckeditor/ckeditor5.svg)](https://david-dm.org/ckeditor/ckeditor5)
 [![devDependency Status](https://img.shields.io/david/dev/ckeditor/ckeditor5.svg)](https://david-dm.org/ckeditor/ckeditor5?type=dev)
 
+[![Join the chat at https://gitter.im/ckeditor/ckeditor5](https://badges.gitter.im/ckeditor/ckeditor5.svg)](https://gitter.im/ckeditor/ckeditor5?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Join newsletter](https://img.shields.io/badge/join-newsletter-00cc99.svg)](http://eepurl.com/c3zRPr)
+[![Follow twitter](https://img.shields.io/badge/follow-twitter-00cc99.svg)](https://twitter.com/ckeditor)
+
 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 editor build screenshot](https://github.com/ckeditor/ckeditor5/blob/master/.github/ckeditor%205%20classic%20screeshot.png)

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

@@ -67,7 +67,7 @@ In order to customize a build you need to:
 The easiest way to install missing dependencies is by typing:
 
 ```bash
-npm install --save <package-name>
+npm install --save-dev <package-name>
 ```
 
 This will install the package and add it to `package.json`. You can also edit `package.json` manually.

+ 244 - 0
docs/builds/guides/development/installing-plugins.md

@@ -0,0 +1,244 @@
+
+menu-title: Installing plugins
+category: builds-development
+order: 30
+---
+
+# Installing plugins
+
+CKEditor 5 plugins are distributed through [npm](https://www.npmjs.com) packages and are implemented in a modular way, which means that a single plugin may consist of multiple JavaScript files.
+
+In this guide you can learn how to add plugins to your editor in the two most common scenarios:
+
+* When you use an {@link builds/guides/overview editor build},
+* When you {@link framework/guides/quick-start build your editor from source}.
+
+## Adding a plugin to a build
+
+Adding plugins to existing builds is done through their customization. Editor builds are maintained in their respective GitHub repositories. Therefore, assuming that you want to customize the [classic editor build](https://npmjs.com/package/@ckeditor/ckeditor5-build-classic) you need to:
+
+1. Clone the build repository.
+2. Install the plugin package.
+3. Add it to the build configuration.
+4. Bundle the build.
+
+```
+git clone -b stable https://github.com/ckeditor/ckeditor5-build-classic.git
+cd ckeditor5-build-classic
+npm install
+```
+
+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:
+
+```
+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: [
+				'headings',
+				'alignmentDropdown', //                      <--- ADDED
+				'bold',
+				'italic',
+				'link',
+				'bulletedList',
+				'numberedList',
+				'blockQuote',
+				'undo',
+				'redo'
+			]
+		},
+
+		image: {
+			toolbar: [ 'imageStyleFull', 'imageStyleSide', '|', 'imageTextAlternative' ]
+		},
+
+		// UI language. Language codes follow the https://en.wikipedia.org/wiki/ISO_639-1 format.
+		language: 'en'
+	}
+};
+```
+
+Finally, bundle the build:
+
+```
+npm run build
+```
+
+If everything worked, the editor build (which is available in the `build/` directory) should be updated.
+
+You can open the `sample/index.html` file in your browser to see whether the plugin was installed correctly.
+
+This was a quick version of how a build can be customized. Read more about {@link builds/guides/development/custom-builds customizing existing editor builds} in a separate guide.
+
+## Adding a plugin to an editor
+
+If you {@link framework/guides/quick-start build the editor from source}, then the process of installing a new plugin boils down to these three steps:
+
+1. Installing the plugin package.
+2. Adding it to your editor's configuration.
+3. Building your project.
+
+For example, if you wish to install the text aligment feature:
+
+```
+npm install --save-dev @ckeditor/ckeditor5-alignment
+```
+
+Edit the code which initializes the editor:
+
+```js
+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 Alignment from '@ckeditor/ckeditor5-aligment/src/alignment'; //   <--- ADDED
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Essentials, Paragraph, Bold, Italic, Aligment ], //   <--- MODIFIED
+		toolbar: [ 'bold', 'italic', 'aligmentDropdown' ] //             <--- MODIFIED
+	} )
+	.then( editor => {
+		console.log( 'Editor was initialized', editor );
+	} )
+	.catch( error => {
+		console.error( error.stack );
+	} );
+```
+
+After rebuilding your project, the new feature will be available in the editor.
+
+<info-box warning>
+	One of the possible mistakes is trying to add a plugin in this way to an existing (bundled) editor build. Installing an existing build and then trying to add a plugin to it may not work if that plugin needs to import any of the source editor modules.
+
+	The reason why this method will not work is that dependencies of the added plugin may duplicate the code already bundled in the used editor build. In the best scenario, this is going to raise the overall code size. In the worst scenario, an application built this way may be unstable.
+</info-box>
+
+## Difference between both methods
+
+What is the difference between adding a plugin to an editor build and adding a plugin by passing the `config.plugins` option to the static `create()` method?
+
+The first method builds the plugin into the editor class. This means that you can then initialize the editor without passing `config.plugins` at all and the editor will automatically enable all built-in plugins:
+
+```js
+// Assuming you use e.g. webpack which can load UMD modules by using ES6 syntax.
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+
+ClassicEditor
+	.create( document.querySelector( 'editor' ), {
+		// Look, ma! No plugins!
+	} )
+	.then( editor => {
+		console.log( 'Editor was initialized', editor );
+	} )
+	.catch( error => {
+		console.error( error.stack );
+	} );
+```
+
+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:
+
+```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';
+// ...
+
+export default class ClassicEditor extends ClassicEditorBase {}
+
+ClassicEditor.build = {
+	plugins: [
+		EssentialsPlugin,
+		UploadadapterPlugin,
+		AutoformatPlugin,
+		BoldPlugin,
+		ItalicPlugin,
+		BlockquotePlugin,
+		// ...
+	],
+	config: {
+		toolbar: {
+			items: [
+				'headings',
+				'bold',
+				// ...
+			]
+		},
+		// ...
+	}
+};
+```
+
+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.
+
+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:
+
+```js
+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';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Essentials, Paragraph, Bold, Italic ],
+		toolbar: [ 'bold', 'italic' ]
+	} )
+	.then( editor => {
+		console.log( 'Editor was initialized', editor );
+	} )
+	.catch( error => {
+		console.error( error.stack );
+	} );
+```
+
+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.

+ 2 - 2
docs/builds/guides/development/plugins.md

@@ -5,7 +5,7 @@
 # * Point to resources to learn plugin development.
 
 category: builds-development
-order: 40
+order: 20
 ---
 
 # Plugins
@@ -45,4 +45,4 @@ A good understanding of the {@link framework/index CKEditor 5 Framework} is also
 
 A great way to enhance your builds with additional features is by using plugins created by the community. Such plugins are generally available as npm packages, so a quick [search on the "ckeditor5" keyword in npm](https://www.npmjs.com/search?q=ckeditor5) should work as a starting point.
 
-Once you have plugins to be included, {@link builds/guides/development/custom-builds create a custom build} configured to include them.
+Once you have plugins to be included, {@link builds/guides/development/installing-plugins learn how to install them}.

File diff suppressed because it is too large
+ 0 - 91
docs/builds/guides/migrate.md


+ 6 - 8
docs/framework/guides/architecture/intro.md

@@ -13,11 +13,9 @@ This guide introduces the most important parts of the CKEditor 5 architecture. I
 
 When implementing features you will usually work with these three CKEditor 5 packages:
 
-* [`@ckeditor/ckeditor5-core`](https://www.npmjs.com/package/@ckeditor/ckeditor5-core) &ndash; The core editor architecture. A couple of core classes and interfaces that glue everything together.
-* [`@ckeditor/ckeditor5-engine`](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine) &ndash; The editing engine. The biggest and by far most complex package, implementing the custom data model, the view layer, conversion mechanisms, rendering engine responsible for [taming `contentEditable`](https://medium.com/content-uneditable/contenteditable-the-good-the-bad-and-the-ugly-261a38555e9c) and a lot more.
-* [`@ckeditor/ckeditor5-ui`](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui) &ndash; The standard UI library. Simple MVC implementation whose main goal is to best fit CKEditor 5 needs.
-
-<!-- TODO link to package pages once https://github.com/cksource/umberto/issues/303 is resolved -->
+* {@link api/core `@ckeditor/ckeditor5-core`} &ndash; The core editor architecture. A couple of core classes and interfaces that glue everything together.
+* {@link api/engine `@ckeditor/ckeditor5-engine`} &ndash; The editing engine. The biggest and by far most complex package, implementing the custom data model, the view layer, conversion mechanisms, rendering engine responsible for [taming `contentEditable`](https://medium.com/content-uneditable/contenteditable-the-good-the-bad-and-the-ugly-261a38555e9c) and a lot more.
+* {@link api/ui `@ckeditor/ckeditor5-ui`} &ndash; The standard UI library. Simple MVC implementation whose main goal is to best fit CKEditor 5 needs.
 
 These packages will be explained one by one.
 
@@ -27,7 +25,7 @@ The [`@ckeditor/ckeditor5-core`](https://www.npmjs.com/package/@ckeditor/ckedito
 
 ### Editor classes
 
-{@link module:core/editor/editor~Editor} class representing the base of the editor.
+The {@link module:core/editor/editor~Editor} class representing the base of the editor.
 
 The editor is a root object, gluing all other components. It holds a couple of properties that you need to know:
 
@@ -46,7 +44,7 @@ Besides that, the editor exposes a few of methods:
 
 You can also extend the editor interface using API interfaces:
 
-* {@link module:core/editor/utils/elementapimixin~ElementApi} &ndash; A way to retrieve and set data from/to element on which editor has been initialized.
+* {@link module:core/editor/utils/elementapimixin~ElementApi} &ndash; A way to retrieve and set data from/to element on which the editor has been initialized.
 * {@link module:core/editor/utils/dataapimixin~DataApi} &ndash; A way to retrieve data from the editor and set data in the editor. The data format is controlled by the {@link module:engine/controller/datacontroller~DataController#processor data controller's data processor} and it does not need to be a string (it can be e.g. JSON if you implement such a {@link module:engine/dataprocessor/dataprocessor~DataProcessor data processor}). See, for example, how to {@link features/markdown produce Markdown output}.
 
 The editor class is a base to implement your own editors. CKEditor 5 Framework comes with a few editor types (for example, {@link module:editor-classic/classiceditor~ClassicEditor classic}, {@link module:editor-inline/inlineeditor~InlineEditor inline} and {@link module:editor-balloon/ballooneditor~BalloonEditor balloon}) but you can freely implement editors which work and look completely different. The only requirement is that you implement the {@link module:core/editor/editor~Editor} interface.
@@ -722,7 +720,7 @@ keystrokeHandler.set( 'Tab', ( keyEvtData, cancel ) => {
 <info-box>
 	There is also an {@link module:core/editingkeystrokehandler~EditingKeystrokeHandler `EditingKeystrokeHandler`} class which has the same API as `KeystrokeHandler` but it offers direct keystroke bindings to editor commands.
 
-	The editor provides such keystroke handler under the {@link module:core/editor/editor~Editor#keystrokes `editor.keystrokes`} property so any plugin can register keystrokes associated with editor commands. For example, the {@link module:undo/undo~Undo `Undo`} plugin registers `editor.keystrokes.set( 'Ctrl+Z', 'undo' );` to execute its "undo" command.
+	The editor provides such keystroke handler under the {@link module:core/editor/editor~Editor#keystrokes `editor.keystrokes`} property so any plugin can register keystrokes associated with editor commands. For example, the {@link module:undo/undo~Undo Undo} plugin registers `editor.keystrokes.set( 'Ctrl+Z', 'undo' );` to execute its `undo` command.
 </info-box>
 
 When multiple callbacks are assigned to the same keystroke, priorities can be used to decide which one should be handled first and whether other callbacks should be executed at all:

+ 3 - 0
scripts/docs/build-docs.js

@@ -14,6 +14,7 @@ const buildApiDocs = require( './buildapi' );
 const skipLiveSnippets = process.argv.includes( '--skip-snippets' );
 const skipApi = process.argv.includes( '--skip-api' );
 const skipValidation = process.argv.includes( '--skip-validation' );
+const dev = process.argv.includes( '--dev' );
 const production = process.argv.includes( '--production' );
 
 buildDocs();
@@ -31,6 +32,7 @@ function buildDocs() {
 			skipLiveSnippets,
 			skipApi,
 			skipValidation,
+			dev,
 			production
 		} ).then( () => process.exit() );
 
@@ -44,6 +46,7 @@ function buildDocs() {
 			return runUmberto( {
 				skipLiveSnippets,
 				skipValidation,
+				dev,
 				production
 			} );
 		} );

+ 1 - 1
scripts/docs/snippetadapter.js

@@ -164,7 +164,7 @@ function runWebpack( webpackConfig ) {
 
 function getModuleResolvePaths() {
 	return [
-		path.resolve( __dirname, '..', '..', '..', 'node_modules' ),
+		path.resolve( __dirname, '..', '..', 'node_modules' ),
 		'node_modules'
 	];
 }

Some files were not shown because too many files changed in this diff