Sfoglia il codice sorgente

Added docs, fixed package.json dependencies.

Szymon Kupś 8 anni fa
parent
commit
2d0cf57fdb

+ 2 - 2
packages/ckeditor5-adapter-ckfinder/package.json

@@ -4,7 +4,8 @@
   "description": "CKFinder adapter for CKEditor 5.",
   "keywords": [],
   "dependencies": {
-	  "@ckeditor/ckeditor5-core": "^0.8.0"
+	  "@ckeditor/ckeditor5-core": "^0.8.0",
+	  "@ckeditor/ckeditor5-upload": "^0.0.1"
   },
   "devDependencies": {
     "@ckeditor/ckeditor5-basic-styles": "^0.8.0",
@@ -18,7 +19,6 @@
     "@ckeditor/ckeditor5-paragraph": "^0.7.0",
     "@ckeditor/ckeditor5-typing": "^0.9.0",
     "@ckeditor/ckeditor5-undo": "^0.8.0",
-    "@ckeditor/ckeditor5-upload": "^0.0.1",
   	"gulp": "^3.9.1",
   	"guppy-pre-commit": "^0.4.0"
   },

+ 62 - 3
packages/ckeditor5-adapter-ckfinder/src/uploadadapter.js

@@ -5,10 +5,27 @@
 
 /* globals XMLHttpRequest, FormData */
 
+/**
+ * @module adapter-ckfinder/uploadadapter
+ */
+
 import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 import FileRepository from '@ckeditor/ckeditor5-upload/src/filerepository';
 import { getCSRFToken } from './utils';
 
+/**
+ * Plugin that enables CKFinder uploads in CKEditor 5.
+ * Configure proper upload URL under `ckfinder.uploadUrl` key, for example:
+ *
+ *	Editor.create( editorElement, {
+ *		plugins: [ ... ],
+ *		ckfinder: {
+ *			uploadUrl: 'http://example.com/upload'
+ *		}
+ *	} );
+ *
+ * @extends module:core/plugin~Plugin
+ */
 export default class CKFinderUploadAdapter extends Plugin {
 	/**
 	 * @inheritDoc
@@ -28,15 +45,34 @@ export default class CKFinderUploadAdapter extends Plugin {
 	}
 }
 
+/**
+ * Upload adapter for CKFinder.
+ *
+ * @private
+ * @implements module:upload/filerepository~Adapter
+ */
 class Adapter {
-	constructor( loader, uploadURL, t ) {
+	/**
+	 * Creates new adapter instance.
+	 *
+	 * @param {module:upload/filerepository~FileLoader} loader
+	 * @param {String} url
+	 * @param {module:utils/locale~Locale#t} t
+	 */
+	constructor( loader, url, t ) {
 		// Save Loader instance to update upload progress.
 		this.loader = loader;
-		this.uploadURL = uploadURL;
+		this.url = url;
 
 		this.t = t;
 	}
 
+	/**
+	 * Starts upload process.
+	 *
+	 * @see module:upload/filerepository~Adapter#upload
+	 * @returns {Promise}
+	 */
 	upload() {
 		return new Promise( ( resolve, reject ) => {
 			this._initRequest();
@@ -45,19 +81,37 @@ class Adapter {
 		} );
 	}
 
+	/**
+	 * Aborts upload process.
+	 *
+	 * @see module:upload/filerepository~Adapter#abort
+	 * @returns {Promise}
+	 */
 	abort() {
 		if ( this.xhr ) {
 			this.xhr.abort();
 		}
 	}
 
+	/**
+	 * Initializes XMLHttpRequest object.
+	 *
+	 * @private
+	 */
 	_initRequest() {
 		const xhr = this.xhr = new XMLHttpRequest();
 
-		xhr.open( 'POST', this.uploadURL, true );
+		xhr.open( 'POST', this.url, true );
 		xhr.responseType = 'json';
 	}
 
+	/**
+	 * Initializes XMLHttpRequest listeners.
+	 *
+	 * @private
+	 * @param {Function} resolve Callback function to be called when request is successful.
+	 * @param {Function} reject Callback function to be called when request cannot be completed.
+	 */
 	_initListeners( resolve, reject ) {
 		const xhr = this.xhr;
 		const loader = this.loader;
@@ -89,6 +143,11 @@ class Adapter {
 		}
 	}
 
+	/**
+	 * Prepares data and sends the request.
+	 *
+	 * @private
+	 */
 	_sendRequest() {
 		// Prepare form data.
 		const data = new FormData();

+ 23 - 1
packages/ckeditor5-adapter-ckfinder/src/utils.js

@@ -5,10 +5,21 @@
 
 /* globals window, document */
 
+/**
+ * @module adapter-ckfinder/utils
+ */
+
 const TOKEN_COOKIE_NAME = 'ckCsrfToken';
 const TOKEN_LENGTH = 40;
 const tokenCharset = 'abcdefghijklmnopqrstuvwxyz0123456789';
 
+/**
+ * Returns the CSRF token value. The value is a hash stored in `document.cookie`
+ * under the `ckCsrfToken` key. The CSRF token can be used to secure the communication
+ * between the web browser and the CKFinder server.
+ *
+ * @returns {String}
+ */
 export function getCSRFToken() {
 	let token = getCookie( TOKEN_COOKIE_NAME );
 
@@ -37,11 +48,22 @@ export function getCookie( name ) {
 	return null;
 }
 
+/**
+ * Sets the value of the cookie with a given name.
+ *
+ * @param {String} name
+ * @param {String} value
+ */
 export function setCookie( name, value ) {
 	document.cookie = encodeURIComponent( name ) + '=' + encodeURIComponent( value ) + ';path=/';
 }
 
-export function generateToken( length ) {
+// Generates CSRF token with given length.
+//
+// @private
+// @param {Number} length
+// @returns {string}
+function generateToken( length ) {
 	let randValues = [];
 	let result = '';