浏览代码

Docs: Extended the CKFinder feature guide with some additional information. Refactoring.

Aleksander Nowodzinski 7 年之前
父节点
当前提交
50976b28f6
共有 1 个文件被更改,包括 50 次插入16 次删除
  1. 50 16
      packages/ckeditor5-ckfinder/docs/features/ckfinder.md

+ 50 - 16
packages/ckeditor5-ckfinder/docs/features/ckfinder.md

@@ -6,11 +6,30 @@ category: features
 
 # CKFinder 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 {@link module:ckfinder/ckfinder~CKFinder feature} allows you to easily {@link features/image-upload 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 can be used in the editor in two different ways:
+
+* [**As a server-side connector only**](#configuring-the-image-upload-only): In this scenario, images which are dropped or pasted into the editor are uploaded to a CKFinder server-side connector running on your server.
+* [**As a server and client-side file manager integration**](#configuring-the-full-integration) **(recommended)**: Images dropped and pasted directly into the editor are uploaded to the server (just like in the first option).
+
+	But there are more cool features available, for instance:
+
+	* **uploading** using the full user interface,
+	* **browsing** previously uploaded images,
+	* **editing** images (cropping, resizing, etc.),
+	* **organizing** or deleting images.
+
+	Use the [demo](#demo) to try the file manager integration with CKEditor 5 now.
+
+	Check out the [CKFinder project website](https://ckeditor.com/ckeditor-4/ckfinder/) to learn more about features you can use in your project.
 
 ## Demo
 
-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 demo shows the [full integration](#configuring-the-full-integration) with the CKFinder file manager:
+
+* You can also paste the image directly into the editor content and it will be automatically uploaded to the server.
+* You can use the "Insert image or file" button in the toolbar to insert an image or a link to any other file.
 
 {@snippet features/ckfinder}
 
@@ -26,7 +45,7 @@ To add this feature to your editor, install the [`@ckeditor/ckeditor5-ckfinder`]
 npm install --save @ckeditor/ckeditor5-ckfinder
 ```
 
-Then add `CKFinder` to your plugin list and [configure](#configuration) the feature (when necessary):
+Then add `CKFinder` to your plugin list and [configure](#configuration) the feature (when necessary), for instance:
 
 ```js
 import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
@@ -49,7 +68,15 @@ The feature can be configured using the {@link module:ckfinder/ckfinder~CKFinder
 
 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.
 
-For instance, the following code will configure the file manager to browse only the specified resource type (in this case: the images):
+<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>
+
+### 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:adapter-ckfinder/uploadadapter~CKFinderAdapterConfig#uploadUrl `config.ckfinder.uploadUrl`} path.
+
+Assuming that the CKFinder file manager is {@link @ckfinder ckfinder3-php/quickstart.html#quickstart_installation_folders installed} (available) 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:
 
 ```js
 import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
@@ -57,28 +84,26 @@ import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		plugins: [ CKFinder, ... ],
-		toolbar: [ 'ckfinder', ... ]
 		ckfinder: {
-			options: {
-				resourceType: 'Images'
-			}
+			// 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'
 		}
 	} )
 	.then( ... )
 	.catch( ... );
 ```
 
-{@snippet features/ckfinder-options}
+Drop an image into the content — it should be uploaded automatically to the server using the CKFinder connector.
+
+### Configuring the full integration
 
 <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.
+	To enable the automatic image upload to the server, follow the [instructions in the previous section](#configuring-the-image-upload-only).
 </info-box>
 
-### Configuring image upload
-
-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:adapter-ckfinder/uploadadapter~CKFinderAdapterConfig#uploadUrl `config.ckfinder.uploadUrl`} path.
+To display the toolbar button that opens the CKFinder file manager UI allowing users to choose files on the server, make sure `'ckfinder'` is present in your {@link module:core/editor/editorconfig~EditorConfig#toolbar `config.toolbar`}.
 
-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:
+Additionally, you can specify {@link @ckfinder ckfinder3/#!/api/CKFinder.Config-cfg-resourceType `config.ckfinder.options.resourceTypes`} to tell the file manager that only the specified resource type (in this case: the images) can be browsed when the user uses the button:
 
 ```js
 import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
@@ -86,16 +111,25 @@ 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's QuickUpload command.
-			uploadUrl: 'https://example.com/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images&responseType=json'
+			// Narrow the list of files that can be browsed.
+			options: {
+				resourceType: 'Images'
+			},
+
+			// ...
 		}
 	} )
 	.then( ... )
 	.catch( ... );
 ```
 
+{@snippet features/ckfinder-options}
+
 ### Configuring the opener
 
 You can change the way the CKFinder file manager opens using the {@link module:ckfinder/ckfinder~CKFinderConfig#openerMethod `config.ckfinder.openerMethod`} option.