Browse Source

Merge pull request #19 from ckeditor/t/18

Docs: Introduced the feature guide. Closes #18. Closes #21.
Aleksander Nowodzinski 7 years ago
parent
commit
0e5a8684bf

+ 11 - 0
packages/ckeditor5-ckfinder/docs/_snippets/features/build-ckfinder-source.html

@@ -0,0 +1,11 @@
+<script src="https://cksource.com/weuy2g4ryt278ywiue/ckfinder.js"></script>
+
+<style>
+	#ckf-modal {
+		z-index: 10101 !important;
+	}
+
+	.ckf-file-preview-root {
+		z-index: 10110 !important;
+	}
+</style>

+ 13 - 0
packages/ckeditor5-ckfinder/docs/_snippets/features/build-ckfinder-source.js

@@ -0,0 +1,13 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals window */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
+
+ClassicEditor.builtinPlugins.push( CKFinder );
+
+window.ClassicEditor = ClassicEditor;

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

@@ -0,0 +1,3 @@
+<div id="snippet-ckfinder-options">
+	Use toolbar button to insert image or link to a file.
+</div>

+ 34 - 0
packages/ckeditor5-ckfinder/docs/_snippets/features/ckfinder-options.js

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-ckfinder-options' ), {
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			items: [
+				'ckfinder', '|', '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=Images&responseType=json',
+			options: {
+				height: 600,
+				width: 800,
+				resourceType: 'Images'
+			}
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

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

@@ -0,0 +1,3 @@
+<div id="snippet-ckfinder">
+	Use toolbar button to insert image or link to a file.
+</div>

+ 33 - 0
packages/ckeditor5-ckfinder/docs/_snippets/features/ckfinder.js

@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-ckfinder' ), {
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			items: [
+				'ckfinder', '|', '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',
+			options: {
+				height: 600,
+				width: 800
+			}
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

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

@@ -6,15 +6,15 @@ 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/image#image-upload CKFinder} feature for CKEditor 5.
+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/).
 
-CKFinder lets you easily insert images which are automatically rescaled, optimized, responsive and delivered through a blazing-fast CDN. It integrates automatically with [CKFinder](https://ckeditor.com/ckfinder/).
+## Demo
 
-## Documentation
+Check out the {@link features/ckfinder#demo demo in the CKFinder feature} guide.
 
-See the {@link features/image-upload Image upload} guide.
+## Documentation
 
-You can also check the {@link module:ckfinder/ckfinder~CKFinder} plugin documentation.
+See the {@link features/ckfinder CKFinder feature} guide and the {@link module:ckfinder/ckfinder~CKFinder} plugin documentation.
 
 ## Installation
 

+ 136 - 0
packages/ckeditor5-ckfinder/docs/features/ckfinder.md

@@ -0,0 +1,136 @@
+---
+category: features
+---
+
+{@snippet features/build-ckfinder-source}
+
+# 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.
+
+## 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.
+
+{@snippet features/ckfinder}
+
+## Installation
+
+<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.
+</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
+```
+
+Then add `CKFinder` to your plugin list and [configure](#configuration) the feature (when necessary):
+
+```js
+import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ CKFinder, ... ],
+		toolbar: [ 'ckfinder', ... ]
+		ckfinder: {
+			// Feature configuration.
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+## Configuration
+
+The feature can be configured using the {@link module:ckfinder/ckfinder~CKFinderConfig `config.ckfinder`} object.
+
+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):
+
+```js
+import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ CKFinder, ... ],
+		toolbar: [ 'ckfinder', ... ]
+		ckfinder: {
+			options: {
+				resourceType: 'Images'
+			}
+		}
+	} )
+	.then( ... )
+	.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>
+
+### 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.
+
+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:
+
+```js
+import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		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'
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+### 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.
+
+By default, the 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';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ CKFinder, ... ],
+		toolbar: [ 'ckfinder', ... ]
+		ckfinder: {
+			// Open the file manager in the popup window.
+			openerMethod: 'popup'
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+## Common API
+
+The {@link module:ckfinder/ckfinder~CKFinder} plugin registers:
+
+* 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:
+
+	```js
+	editor.execute( 'ckfinder' );
+	```
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-ckfinder.