Browse Source

Merge branch 'master' into t/ckeditor5-utils/257

Aleksander Nowodzinski 7 years ago
parent
commit
6bdf2cf041

+ 6 - 0
packages/ckeditor5-ckfinder/CHANGELOG.md

@@ -0,0 +1,6 @@
+Changelog
+=========
+
+## [10.0.0](https://github.com/ckeditor/ckeditor5-ckfinder/tree/v10.0.0) (2018-12-05)
+
+Initial implementation of the CKFinder file manager integration feature.

+ 4 - 2
packages/ckeditor5-ckfinder/README.md

@@ -10,11 +10,13 @@ CKEditor 5's CKFinder integration
 [![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-ckfinder/status.svg)](https://david-dm.org/ckeditor/ckeditor5-ckfinder)
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-ckfinder/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-ckfinder?type=dev)
 
-The [CKFinder](https://ckeditor.com/ckfinder/) file browser integration for CKEditor 5.
+This package implements the [CKFinder feature](https://ckeditor.com/docs/ckeditor5/latest/features/ckfinder.html). This feature allows you to easily insert images as well as links to files into the editor content. It is a bridge between the CKEditor 5 WYSIWYG editor and the [CKFinder file manager and uploader](https://ckeditor.com/ckfinder).
 
 ## Documentation
 
-See the [`@ckeditor/ckeditor5-ckfinder` package](https://ckeditor.com/docs/ckeditor5/latest/api/ckfinder.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
+See the ["CKFinder integration" guide](https://ckeditor.com/docs/ckeditor5/latest/features/ckfinder.html) and the [plugin documentation](https://ckeditor.com/docs/ckeditor5/latest/api/ckfinder.html) to learn more about the integration.
+
+Check out the [comprehensive "Image upload" guide](https://ckeditor.com/docs/ckeditor5/latest/features/image-upload.html) to learn about other ways to upload images into CKEditor 5.
 
 ## License
 

+ 3 - 0
packages/ckeditor5-ckfinder/docs/_snippets/features/ckfinder-upload-only.html

@@ -0,0 +1,3 @@
+<div id="snippet-ckfinder-upload-only">
+	Use the toolbar button to insert an image.
+</div>

+ 26 - 0
packages/ckeditor5-ckfinder/docs/_snippets/features/ckfinder-upload-only.js

@@ -0,0 +1,26 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-ckfinder-upload-only' ), {
+		toolbar: {
+			items: [
+				'imageUpload', '|', 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo'
+			],
+			viewportTopOffset: 100
+		},
+		ckfinder: {
+			// eslint-disable-next-line max-len
+			uploadUrl: 'https://cksource.com/weuy2g4ryt278ywiue/core/connector/php/connector.php?command=QuickUpload&type=Files&responseType=json'
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 1 - 1
packages/ckeditor5-ckfinder/docs/_snippets/features/ckfinder.html

@@ -1,3 +1,3 @@
 <div id="snippet-ckfinder">
-	Use toolbar button to insert image or link to a file.
+	Use the toolbar button to open the CKFinder file manager. Use the file manager's interface to insert an image or a link to a file.
 </div>

+ 5 - 3
packages/ckeditor5-ckfinder/docs/api/ckfinder.md

@@ -6,15 +6,17 @@ category: api-reference
 
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-ckfinder.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-ckfinder)
 
-This package implements the {@link features/ckfinder CKFinder integration} feature for CKEditor 5. It lets you easily insert images & links to files. It integrates automatically with [CKFinder](https://ckeditor.com/ckfinder/).
+This package implements the {@link features/ckfinder CKFinder feature}. This feature allows you to easily insert images as well as links to files into the editor content. It is a bridge between the CKEditor 5 WYSIWYG editor and the [CKFinder file manager and uploader](https://ckeditor.com/ckfinder).
 
 ## Demo
 
-Check out the {@link features/ckfinder#demo demo in the CKFinder feature} guide.
+Check out the {@link features/ckfinder#demo demos} in the integration guide.
 
 ## Documentation
 
-See the {@link features/ckfinder CKFinder feature} guide and the {@link module:ckfinder/ckfinder~CKFinder} plugin documentation.
+See the {@link features/ckfinder "CKFinder integration" guide} and the {@link module:ckfinder/ckfinder~CKFinder plugin documentation} to learn more about the integration.
+
+Check out the {@link features/image-upload comprehensive "Image upload" guide} to learn about other ways to upload images into CKEditor 5.
 
 ## Installation
 

+ 107 - 38
packages/ckeditor5-ckfinder/docs/features/ckfinder.md

@@ -1,32 +1,68 @@
 ---
-category: features
+category: features-image-upload
+menu-title: CKFinder file manager
+order: 30
 ---
 
 {@snippet features/build-ckfinder-source}
 
-# CKFinder integration
+# CKFinder file manager integration
 
-This {@link module:ckfinder/ckfinder~CKFinder feature} allows you to easily insert images as well as links to files into the editor content. It is a bridge between the CKEditor 5 WYSIWYG editor and the [CKFinder](https://ckeditor.com/ckfinder) file manager and uploader.
+This feature allows you to insert images as well as links to files into the rich-text editor content. It is a bridge between the CKEditor 5 WYSIWYG editor and the [CKFinder](https://ckeditor.com/ckfinder) file manager and uploader.
 
-## Demo
+<info-box>
+	Check out the comprehensive {@link features/image-upload Image upload overview} to learn about other ways to upload images into CKEditor 5.
+</info-box>
 
-You can use the "Insert image or file" button in the toolbar to insert an image or a link to any other file. You can also paste the image directly into the editor content and it will be automatically [uploaded](#configuring-image-upload) to the server.
+This feature can be used in the rich-text editor in two different ways:
 
-{@snippet features/ckfinder}
+* [**As a server-side connector only**](#configuring-the-image-upload-only) ([demo](#image-upload-only)). In this scenario, images which are dropped or pasted into the editor are uploaded to the CKFinder server-side connector running on your server.
+* [**As a server and client-side file manager integration**](#configuring-the-full-integration) ([demo](#full-integration)). Images dropped and pasted directly into the editor are uploaded to the server (just like in the first option).
 
-## Installation
+	But there are more cool features available, for instance:
+
+	* **uploading** using the full user interface,
+	* uploading **multiple files** at once,
+	* **browsing** previously uploaded images,
+	* **editing** images (cropping, resizing, etc.),
+	* **organizing** or deleting images.
+
+	Check out the [CKFinder file manager website](https://ckeditor.com/ckfinder/) to learn more about the features you can use in your project.
 
 <info-box info>
-	This feature is enabled by default in all builds. The installation instructions are for developers interested in building their own, custom editor.
+	This feature is enabled by default in all builds.
 </info-box>
 
-To add this feature to your editor, install the [`@ckeditor/ckeditor5-ckfinder`](https://www.npmjs.com/package/@ckeditor/ckeditor5-ckfinder) package:
+## Demo
 
-```bash
-npm install --save @ckeditor/ckeditor5-ckfinder
-```
+### Image upload only
+
+This demo shows the integration where the file manager's server connector handles [the image upload](#configuring-the-full-integration) only:
+
+* Paste the image directly into the rich-text editor content and it will be automatically uploaded using the server-side connector.
+* Use the "Insert image" button in the toolbar to insert an image.
+
+{@snippet features/ckfinder-upload-only}
 
-Then add `CKFinder` to your plugin list and [configure](#configuration) the feature (when necessary):
+### Full integration
+
+This demo shows the [full integration](#configuring-the-full-integration) with the CKFinder file uploader:
+
+* Paste the image directly into the rich-text editor content and it will be automatically uploaded using the server-side connector.
+* Use the "Insert image or file" button in the toolbar to open the CKFinder file manager and insert an image or a link to any other file.
+
+{@snippet features/ckfinder}
+
+
+## Configuration
+
+The feature is configurable by using the {@link module:ckfinder/ckfinder~CKFinderConfig `config.ckfinder`} object.
+
+### Configuring the image upload only
+
+This feature can upload images automatically to the server (e.g. when the image is dropped into the content) thanks to the {@link module:adapter-ckfinder/uploadadapter~CKFinderUploadAdapter CKFinder upload adapter}. All it requires is the correct {@link module:ckfinder/ckfinder~CKFinderConfig#uploadUrl `config.ckfinder.uploadUrl`} path.
+
+Assuming that the [CKFinder PHP server-side connector is installed](https://ckeditor.com/docs/ckfinder/ckfinder3-php/quickstart.html#quickstart_installation_folders) (available) under `https://example.com/ckfinder/`, use the following [quick upload](https://ckeditor.com/docs/ckfinder/ckfinder3-php/commands.html#command_quick_upload) command URL to enable the image upload:
 
 ```js
 import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
@@ -34,22 +70,39 @@ import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		plugins: [ CKFinder, ... ],
-		toolbar: [ 'ckfinder', ... ]
+
+		// Enable the "Insert image" button in the toolbar.
+		toolbar: [ 'imageUpload', ... ],
+
 		ckfinder: {
-			// Feature configuration.
+			// Upload the images to the server using the CKFinder QuickUpload command.
+			uploadUrl: 'https://example.com/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images&responseType=json'
 		}
 	} )
 	.then( ... )
 	.catch( ... );
 ```
 
-## Configuration
+See the **[demo of the image upload only](#image-upload-only)**.
+
+### Configuring the full integration
+
+To use both the image upload functionality and the file manager user interface in your application, you must first load the CKFinder JavaScript library and then enable CKFinder integration in your rich-text editor instance.
 
-The feature can be configured using the {@link module:ckfinder/ckfinder~CKFinderConfig `config.ckfinder`} object.
+The easiest way to load the CKFinder library is to include the `<script>` tag loading the `ckfinder.js` file first:
 
-The file manager configuration can be passed through the {@link module:ckfinder/ckfinder~CKFinderConfig#options `config.ckfinder.options`} object. Check the {@link @ckfinder ckfinder3/#!/api/CKFinder.Config file manager documentation} for the complete list of options.
+```html
+<script src="https://example.com/ckfinder/ckfinder.js"></script>
+```
+
+Then:
 
-For instance, the following code will configure the file manager to browse only the specified resource type (in this case: the images):
+* Make sure that the {@link module:ckfinder/ckfinder~CKFinder CKFinder plugin} for CKEditor 5 is enabled. See the [Installation](#installation) section.
+* In order to enable the automatic file upload to the server when an image is pasted or dropped into the editor content, remember to set the correct {@link module:ckfinder/ckfinder~CKFinderConfig#uploadUrl `config.ckfinder.uploadUrl`} path.
+* In order to display the toolbar button that opens the CKFinder file manager UI allowing the users to choose the files on the server, make sure that `'ckfinder'` is present in your {@link module:core/editor/editorconfig~EditorConfig#toolbar `config.toolbar`}.
+* Additionally, you can use {@link module:ckfinder/ckfinder~CKFinderConfig#options `config.ckfinder.options`} to define [CKFinder's options](https://ckeditor.com/docs/ckfinder/ckfinder3/#!/api/CKFinder.Config). For example:
+	* You can define [`options.resourceType`](https://ckeditor.com/docs/ckfinder/ckfinder3/#!/api/CKFinder.Config-cfg-resourceType) to tell CKFinder the specified resource type can be browsed when the user clicks the button.
+	* You can define [`options.language`](https://ckeditor.com/docs/ckfinder/ckfinder3/#!/api/CKFinder.Config-cfg-language) to set the UI language of CKFinder. By default it will be set to the UI language of the editor.
 
 ```js
 import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
@@ -57,8 +110,15 @@ import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		plugins: [ CKFinder, ... ],
+
+		// Enable the CKFinder button in the toolbar.
 		toolbar: [ 'ckfinder', ... ]
+
 		ckfinder: {
+			// Upload the images to the server using the CKFinder QuickUpload command.
+			uploadUrl: 'https://example.com/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images&responseType=json',
+
+			// Define the CKFinder configuration (if necessary).
 			options: {
 				resourceType: 'Images'
 			}
@@ -68,17 +128,13 @@ ClassicEditor
 	.catch( ... );
 ```
 
-{@snippet features/ckfinder-options}
-
-<info-box>
-	By default, the editor language is automatically passed to the file manager — the file manager "inherits" the language of the editor. This behavior can be changed by setting the `ckfinder.options.language` configuration option.
-</info-box>
+See the **[demo of the full integration](#full-integration)**.
 
-### Configuring image upload
+#### Configuring the opener
 
-This feature allows you to not only browse images, but also upload them automatically to the server (e.g. when the image is dropped into the content) thanks to the {@link module:adapter-ckfinder/uploadadapter~CKFinderUploadAdapter CKFinder upload adapter}. All it requires is the correct {@link module:ckfinder/ckfinder~CKFinderConfig#uploadUrl `config.ckfinder.uploadUrl`} path.
+You can change the way CKFinder opens using the {@link module:ckfinder/ckfinder~CKFinderConfig#openerMethod `config.ckfinder.openerMethod`} option.
 
-Assuming that the CKFinder file manager is {@link @ckfinder ckfinder3-php/quickstart.html#quickstart_installation_folders installed} (accessible) under `https://example.com/ckfinder/`, use the following {@link @ckfinder ckfinder3-php/commands.html#command_quick_upload quick upload} command URL to enable the image upload:
+By default, the file manager opens as a modal. To open it in a new "pop-up" window, set the configuration value to `popup`:
 
 ```js
 import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
@@ -88,19 +144,27 @@ ClassicEditor
 		plugins: [ CKFinder, ... ],
 		toolbar: [ 'ckfinder', ... ]
 		ckfinder: {
-			// Upload the images to the server using the CKFinder's QuickUpload command.
-			uploadUrl: 'https://example.com/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images&responseType=json'
+			// Open the file manager in the pop-up window.
+			openerMethod: 'popup'
 		}
 	} )
 	.then( ... )
 	.catch( ... );
 ```
 
-### Configuring the opener
+## Installation
 
-You can change the way the CKFinder file manager opens using the {@link module:ckfinder/ckfinder~CKFinderConfig#openerMethod `config.ckfinder.openerMethod`} option.
+<info-box info>
+	This feature is enabled by default in all builds. The installation instructions are for developers interested in building their own, custom WYSIWYG editor.
+</info-box>
+
+To add this feature to your editor, install the [`@ckeditor/ckeditor5-ckfinder`](https://www.npmjs.com/package/@ckeditor/ckeditor5-ckfinder) package:
+
+```bash
+npm install --save @ckeditor/ckeditor5-ckfinder
+```
 
-By default, the manager opens as a modal. To open it in a new "pop-up" window, set the configuration value to `popup`:
+Then add {@link module:ckfinder/ckfinder~CKFinder} to your plugin list and [configure](#configuration) the feature (when necessary). For instance:
 
 ```js
 import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
@@ -108,10 +172,9 @@ import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		plugins: [ CKFinder, ... ],
-		toolbar: [ 'ckfinder', ... ]
+		toolbar: [ 'ckfinder', 'imageUpload' ... ], // Depending on your preference.
 		ckfinder: {
-			// Open the file manager in the popup window.
-			openerMethod: 'popup'
+			// Feature configuration.
 		}
 	} )
 	.then( ... )
@@ -122,15 +185,21 @@ ClassicEditor
 
 The {@link module:ckfinder/ckfinder~CKFinder} plugin registers:
 
-* the `'ckfinder'` UI button component,
-* the `'ckfinder'` command implemented by the {@link module:ckfinder/ckfindercommand~CKFinderCommand}.
+* The `'ckfinder'` UI button component.
+* The `'ckfinder'` command implemented by the {@link module:ckfinder/ckfindercommand~CKFinderCommand}.
 
-	You can open a CKFinder by executing the following code:
+	You can open CKFinder by executing the following code:
 
 	```js
 	editor.execute( 'ckfinder' );
 	```
 
+Additionally, in the "image upload only" integration, you can use the following button and command registered by the {@link module:image/imageupload~ImageUpload} plugin:
+
+* The `'imageUpload'` UI button component.
+* The `'imageUpload'` command implemented by the {@link module:image/imageupload/imageuploadcommand~ImageUploadCommand}.
+
 ## Contribute
 
 The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-ckfinder.
+

+ 12 - 12
packages/ckeditor5-ckfinder/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-ckfinder",
-  "version": "0.0.1",
+  "version": "10.0.0",
   "description": "CKFinder integration for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -10,19 +10,19 @@
     "ckeditor5-plugin"
   ],
   "dependencies": {
-    "@ckeditor/ckeditor5-adapter-ckfinder": "^10.0.3",
-    "@ckeditor/ckeditor5-core": "^11.0.1",
-    "@ckeditor/ckeditor5-ui": "^11.1.0",
-    "@ckeditor/ckeditor5-widget": "^10.3.0"
+    "@ckeditor/ckeditor5-adapter-ckfinder": "^10.0.4",
+    "@ckeditor/ckeditor5-core": "^11.1.0",
+    "@ckeditor/ckeditor5-ui": "^11.2.0",
+    "@ckeditor/ckeditor5-widget": "^10.3.1"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-editor-classic": "^11.0.1",
-    "@ckeditor/ckeditor5-clipboard": "^10.0.3",
-    "@ckeditor/ckeditor5-engine": "^11.0.0",
-    "@ckeditor/ckeditor5-image": "^11.0.0",
-    "@ckeditor/ckeditor5-link": "^10.0.4",
-    "@ckeditor/ckeditor5-paragraph": "^10.0.3",
-    "@ckeditor/ckeditor5-utils": "^11.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^11.0.2",
+    "@ckeditor/ckeditor5-clipboard": "^10.0.4",
+    "@ckeditor/ckeditor5-engine": "^12.0.0",
+    "@ckeditor/ckeditor5-image": "^12.0.0",
+    "@ckeditor/ckeditor5-link": "^10.1.0",
+    "@ckeditor/ckeditor5-paragraph": "^10.0.4",
+    "@ckeditor/ckeditor5-utils": "^11.1.0",
     "eslint": "^5.5.0",
     "eslint-config-ckeditor5": "^1.0.7",
     "husky": "^0.14.3",

+ 10 - 2
packages/ckeditor5-ckfinder/src/ckfinder.js

@@ -14,12 +14,20 @@ import CKFinderEditing from './ckfinderediting';
 import CKFinderUploadAdapter from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
 
 /**
- * The CKFinder feature.
+ * The CKFinder feature, a bridge between the CKEditor 5 WYSIWYG editor and the
+ * [CKFinder](https://ckeditor.com/ckfinder) file manager and uploader.
  *
  * This is a "glue" plugin which enables:
  *
  * * {@link module:ckfinder/ckfinderediting~CKFinderEditing},
- * * {@link module:ckfinder/ckfinderui~CKFinderUI}.
+ * * {@link module:ckfinder/ckfinderui~CKFinderUI},
+ * * {@link module:adapter-ckfinder/uploadadapter~CKFinderUploadAdapter}.
+ *
+ * See the {@glink features/image-upload/ckfinder "CKFinder integration" guide} to learn how to configure
+ * and use this feature.
+ *
+ * Check out the {@glink features/image-upload/image-upload comprehensive "Image upload" guide} to learn about
+ * other ways to upload images into CKEditor 5.
  *
  * @extends module:core/plugin~Plugin
  */

+ 2 - 3
packages/ckeditor5-ckfinder/src/ckfindercommand.js

@@ -10,7 +10,6 @@
  */
 
 import Command from '@ckeditor/ckeditor5-core/src/command';
-import Notification from '@ckeditor/ckeditor5-ui/src/notification/notification';
 import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 
 /**
@@ -105,7 +104,7 @@ export default class CKFinderCommand extends Command {
 				const resizedUrl = evt.data.resizedUrl;
 
 				if ( !resizedUrl ) {
-					const notification = editor.plugins.get( Notification );
+					const notification = editor.plugins.get( 'Notification' );
 					const t = editor.locale.t;
 
 					notification.showWarning( t( 'Could not obtain resized image URL.' ), {
@@ -129,7 +128,7 @@ function insertImages( editor, urls ) {
 
 	// Check if inserting an image is actually possible - it might be possible to only insert a link.
 	if ( !imageCommand.isEnabled ) {
-		const notification = editor.plugins.get( Notification );
+		const notification = editor.plugins.get( 'Notification' );
 		const t = editor.locale.t;
 
 		notification.showWarning( t( 'Could not insert image at the current position.' ), {