Skip to content

Commit af2f724

Browse files
AnnaTomanekAnnaTomanek
committed
Docs & language strings: uploadwidget and uploadimage files corrected.
1 parent 2b01e55 commit af2f724

File tree

3 files changed

+83
-83
lines changed

3 files changed

+83
-83
lines changed

‎plugins/uploadimage/plugin.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@
105105
// jscs:enable maximumLineLength
106106

107107
/**
108-
* URL where images should be uploaded.
108+
* The URL where images should be uploaded.
109109
*
110110
* @since 4.5
111111
* @cfg {String} [imageUploadUrl='' (empty string = disabled)]

‎plugins/uploadwidget/lang/en.js

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,9 @@
44
*/
55

66
CKEDITOR.plugins.setLang( 'uploadwidget', 'en', {
7-
abort: 'Upload aborted by user.',
7+
abort: 'Upload aborted by the user.',
88
doneOne: 'File successfully uploaded.',
99
doneMany: 'Successfully uploaded %1 files.',
1010
uploadOne: 'Uploading file ({percentage}%)...',
1111
uploadMany: 'Uploading files, {current} of {max} done ({percentage}%)...'
12-
13-
} );
12+
} );

‎plugins/uploadwidget/plugin.js

Lines changed: 80 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -19,27 +19,27 @@
1919
} );
2020

2121
/**
22-
* This function creates an upload widget - a placeholder to show the the progress of an upload. The upload widget
23-
* is based on its {@link CKEDITOR.fileTools.uploadWidgetDefinition definition}. `addUploadWidget` function also
24-
* creates a paste event, if {@link CKEDITOR.fileTools.uploadWidgetDefinition#fileToElement fileToElement} method
25-
* is defined. This event is helpful to handle pasted files, it will automatically check if files were pasted and
26-
* and mark them to be uploaded.
27-
*
28-
* Upload widget helps to handle content being asynchronously uploaded inside the editor. It solves problems such as:
29-
* editing during upload, undo manager integration, getting data, removing or copying uploading element.
30-
*
31-
* To create upload widget you need to define two transformation methods:
32-
*
33-
* * {@link CKEDITOR.fileTools.uploadWidgetDefinition#fileToElement fileToElement} method which will be called on `paste`
34-
* and transform file into placeholder,
35-
* * {@link CKEDITOR.fileTools.uploadWidgetDefinition#onUploaded onUploaded} with
36-
* {@link CKEDITOR.fileTools.uploadWidgetDefinition#replaceWith replaceWith} method which will be called to replace
37-
* upload placeholder with the final HTML when upload is done.
38-
* If you want to show an additional progress you can also define
39-
* {@link CKEDITOR.fileTools.uploadWidgetDefinition#onLoading onLoading} and
22+
* This function creates an upload widget — a placeholder to show the progress of an upload. The upload widget
23+
* is based on its {@link CKEDITOR.fileTools.uploadWidgetDefinition definition}. The `addUploadWidget` method also
24+
* creates a `paste` event, if the {@link CKEDITOR.fileTools.uploadWidgetDefinition#fileToElement fileToElement} method
25+
* is defined. This event helps in handling pasted files, as it will automatically check if the files were pasted and
26+
* mark them to be uploaded.
27+
*
28+
* The upload widget helps to handle content that is uploaded asynchronously inside the editor. It solves issues such as:
29+
* editing during upload, undo manager integration, getting data, removing or copying uploaded element.
30+
*
31+
* To create an upload widget you need to define two transformation methods:
32+
*
33+
* * The {@link CKEDITOR.fileTools.uploadWidgetDefinition#fileToElement fileToElement} method which will be called on
34+
* `paste` and transform a file into a placeholder.
35+
* * The {@link CKEDITOR.fileTools.uploadWidgetDefinition#onUploaded onUploaded} method with
36+
* the {@link CKEDITOR.fileTools.uploadWidgetDefinition#replaceWith replaceWith} method which will be called to replace
37+
* the upload placeholder with the final HTML when the upload is done.
38+
* If you want to show more information about the progress you can also define
39+
* the {@link CKEDITOR.fileTools.uploadWidgetDefinition#onLoading onLoading} and
4040
* {@link CKEDITOR.fileTools.uploadWidgetDefinition#onUploading onUploading} methods.
4141
*
42-
* The simplest uploading widget which uploads file and creates a link to it, may looks like this:
42+
* The simplest uploading widget which uploads a file and creates a link to it may look like this:
4343
*
4444
* CKEDITOR.fileTools.addUploadWidget( editor, 'uploadfile', {
4545
* uploadUrl: CKEDITOR.fileTools.getUploadUrl( editor.config ),
@@ -56,15 +56,16 @@
5656
* }
5757
* } );
5858
*
59-
* Upload widget use {@link CKEDITOR.fileTools.fileLoader} as a helper to upload file. {@link CKEDITOR.fileTools.fileLoader}
60-
* instance is created when the file is pasted and proper method is called, by default it is
61-
* {@link CKEDITOR.fileTools.fileLoader#loadAndUpload} method. If you want to use only `load`
62-
* or only `upload` you can use {@link CKEDITOR.fileTools.uploadWidgetDefinition#loadMethod loadMethod} property.
59+
* The upload widget uses {@link CKEDITOR.fileTools.fileLoader} as a helper to upload the file. A
60+
* {@link CKEDITOR.fileTools.fileLoader} instance is created when the file is pasted and a proper method is
61+
* called — by default it is the {@link CKEDITOR.fileTools.fileLoader#loadAndUpload} method. If you want
62+
* to only use the `load` or `upload`, you can use the {@link CKEDITOR.fileTools.uploadWidgetDefinition#loadMethod loadMethod}
63+
* property.
6364
*
6465
* Note that if you want to handle a big file, e.g. a video, you may need to use `upload` instead of
65-
* `loadAndUpload` because the file may be to too big to load it to the memory at once.
66+
* `loadAndUpload` because the file may be too big to load it to memory at once.
6667
*
67-
* Note that if you do not upload file you need to define {@link CKEDITOR.fileTools.uploadWidgetDefinition#onLoaded onLoaded}
68+
* If you do not upload the file, you need to define {@link CKEDITOR.fileTools.uploadWidgetDefinition#onLoaded onLoaded}
6869
* instead of {@link CKEDITOR.fileTools.uploadWidgetDefinition#onUploaded onUploaded}.
6970
* For example, if you want to read the content of the file:
7071
*
@@ -83,9 +84,9 @@
8384
* }
8485
* } );
8586
*
86-
* Note that if you need a custom `paste` handling you need to mark pasted element to be changed into upload widget
87-
* using {@link CKEDITOR.fileTools#markElement markElement}. For example, instead of `fileToElement` helper from the
88-
* example above, `paste` listener can be created manually:
87+
* If you need custom `paste` handling you need to mark the pasted element to be changed into an upload widget
88+
* using {@link CKEDITOR.fileTools#markElement markElement}. For example, instead of the `fileToElement` helper from the
89+
* example above, a `paste` listener can be created manually:
8990
*
9091
* editor.on( 'paste', function( evt ) {
9192
* var file, i, el, loader;
@@ -110,8 +111,8 @@
110111
*
111112
* Note that you can bind notifications to the upload widget on paste using
112113
* the {@link CKEDITOR.fileTools#bindNotifications} method, so notifications will automatically
113-
* show the progress of the upload. Because this method shows notification about upload do not use it if you only
114-
* {@link CKEDITOR.fileTools.fileLoader#load load} (not upload) file.
114+
* show the progress of the upload. Because this method shows notifications about upload, do not use it if you only
115+
* {@link CKEDITOR.fileTools.fileLoader#load load} (and not upload) a file.
115116
*
116117
* editor.on( 'paste', function( evt ) {
117118
* var file, i, el, loader;
@@ -187,24 +188,24 @@
187188
* This is an abstract class that describes a definition of an upload widget.
188189
* It is a type of {@link CKEDITOR.fileTools#addUploadWidget} method's second argument.
189190
*
190-
* Note that, because upload widget is a type of a widget, this definition extends
191+
* Note that because the upload widget is a type of a widget, this definition extends
191192
* {@link CKEDITOR.plugins.widget.definition}.
192193
* It adds several new properties and callbacks and implements the {@link CKEDITOR.plugins.widget.definition#downcast}
193194
* and {@link CKEDITOR.plugins.widget.definition#init} callbacks. These two properties
194195
* should not be overwritten.
195196
*
196-
* Also, upload widget definition defines few properties ({@link #fileToElement}, {@link #supportedTypes},
197+
* Also, the upload widget definition defines a few properties ({@link #fileToElement}, {@link #supportedTypes},
197198
* {@link #loadMethod loadMethod} and {@link #uploadUrl}) used in the {@link CKEDITOR.editor#paste} listener
198199
* which is registered by {@link CKEDITOR.fileTools#addUploadWidget} if the upload widget definition contains
199-
* {@link #fileToElement} callback.
200+
* the {@link #fileToElement} callback.
200201
*
201202
* @abstract
202203
* @class CKEDITOR.fileTools.uploadWidgetDefinition
203204
* @mixins CKEDITOR.plugins.widget.definition
204205
*/
205206
CKEDITOR.tools.extend( def, {
206207
/**
207-
* Upload widget definition overwrites {@link CKEDITOR.plugins.widget.definition#downcast} property.
208+
* Upload widget definition overwrites the {@link CKEDITOR.plugins.widget.definition#downcast} property.
208209
* This should not be changed.
209210
*
210211
* @property {String/Function}
@@ -214,7 +215,7 @@
214215
},
215216

216217
/**
217-
* Upload widget definition overwrites {@link CKEDITOR.plugins.widget.definition#init}.
218+
* Upload widget definition overwrites the {@link CKEDITOR.plugins.widget.definition#init} property.
218219
* If you want to add some code in the `init` callback remember to call the base function.
219220
*
220221
* @property {Function}
@@ -269,8 +270,8 @@
269270
},
270271

271272
/**
272-
* Replaces upload widget with the final HTML. This method should be called when upload is done,
273-
* in common case in the {@link #onUploaded} callback.
273+
* Replaces the upload widget with the final HTML. This method should be called when the upload is done,
274+
* usually in the {@link #onUploaded} callback.
274275
*
275276
* @property {Function}
276277
* @param {String} data HTML to replace the upload widget.
@@ -316,109 +317,109 @@
316317
}
317318

318319
/**
319-
* If this property is defined, paste listener is created to transform pasted file into HTML element.
320-
* It creates HTML element which will be then transformed into an upload widget.
320+
* If this property is defined, paste listener is created to transform the pasted file into an HTML element.
321+
* It creates an HTML element which will be then transformed into an upload widget.
321322
* It is only called for {@link #supportedTypes supported files}.
322-
* If multiple files have been pasted this function will be called for each file of supported type.
323+
* If multiple files were pasted, this function will be called for each file of a supported type.
323324
*
324325
* @property {Function} fileToElement
325-
* @param {Blob} file Pasted file to load or upload.
326-
* @returns {CKEDITOR.dom.element} Element which will be transformed into the upload widget.
326+
* @param {Blob} file A pasted file to load or upload.
327+
* @returns {CKEDITOR.dom.element} An element which will be transformed into the upload widget.
327328
*/
328329

329330
/**
330331
* Regular expression to check if the file type is supported by this widget.
331-
* If not defined all files will be handled.
332+
* If not defined, all files will be handled.
332333
*
333334
* @property {String} [supportedTypes]
334335
*/
335336

336337
/**
337-
* URL to which the file will be uploaded. It should be taken from configuration using
338+
* The URL to which the file will be uploaded. It should be taken from the configuration using
338339
* {@link CKEDITOR.fileTools#getUploadUrl}.
339340
*
340341
* @property {String} [uploadUrl]
341342
*/
342343

343344
/**
344-
* What type of loading operation should be executed as a result of pasting file. Possible options are:
345+
* The type of loading operation that should be executed as a result of pasting a file. Possible options are:
345346
*
346-
* * 'loadAndUpload' - default behavior, {@link CKEDITOR.fileTools.fileLoader#loadAndUpload} method will be
347-
* executed, file will be loaded first and uploaded immediately after loading is done,
348-
* * 'load' - {@link CKEDITOR.fileTools.fileLoader#load} method will be executed, this loading type should
349-
* be used if you want only load file data without uploading it,
350-
* * 'upload' - {@link CKEDITOR.fileTools.fileLoader#upload} method will be executed, file will be uploaded,
351-
* without loading it to the memory, this loading type should be used if you want to upload big file,
352-
* otherwise you can meet out of memory error.
347+
* * 'loadAndUpload' – Default behavior, the {@link CKEDITOR.fileTools.fileLoader#loadAndUpload} method will be
348+
* executed, the file will be loaded first and uploaded immediately after loading is done.
349+
* * 'load' – The {@link CKEDITOR.fileTools.fileLoader#load} method will be executed. This loading type should
350+
* be used if you only want to load file data without uploading it.
351+
* * 'upload' – The {@link CKEDITOR.fileTools.fileLoader#upload} method will be executed, the file will be uploaded
352+
* without loading it to memory. This loading type should be used if you want to upload a big file,
353+
* otherwise you can get an "out of memory" error.
353354
*
354355
* @property {String} [loadMethod=loadAndUpload]
355356
*/
356357

357358
/**
358-
* Function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `loading`.
359+
* A function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `loading`.
359360
*
360361
* @property {Function} [onLoading]
361-
* @param {CKEDITOR.fileTools.fileLoader} loader Loaders instance.
362+
* @param {CKEDITOR.fileTools.fileLoader} loader Loader instance.
362363
* @returns {Boolean}
363364
*/
364365

365366
/**
366-
* Function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `loaded`.
367+
* A function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `loaded`.
367368
*
368369
* @property {Function} [onLoaded]
369-
* @param {CKEDITOR.fileTools.fileLoader} loader Loaders instance.
370+
* @param {CKEDITOR.fileTools.fileLoader} loader Loader instance.
370371
* @returns {Boolean}
371372
*/
372373

373374
/**
374-
* Function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `uploading`.
375+
* A function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `uploading`.
375376
*
376377
* @property {Function} [onUploading]
377-
* @param {CKEDITOR.fileTools.fileLoader} loader Loaders instance.
378+
* @param {CKEDITOR.fileTools.fileLoader} loader Loader instance.
378379
* @returns {Boolean}
379380
*/
380381

381382
/**
382-
* Function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `uploaded`.
383-
* At that point upload is done and the uploading widget should we replaced with the final HTML using
384-
* {@link #replaceWith} method.
383+
* A function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `uploaded`.
384+
* At that point the upload is done and the upload widget should be replaced with the final HTML using
385+
* the {@link #replaceWith} method.
385386
*
386387
* @property {Function} [onUploaded]
387-
* @param {CKEDITOR.fileTools.fileLoader} loader Loaders instance.
388+
* @param {CKEDITOR.fileTools.fileLoader} loader Loader instance.
388389
* @returns {Boolean}
389390
*/
390391

391392
/**
392-
* Function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `error`.
393+
* A function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `error`.
393394
* The default behavior is to remove the widget and it can be canceled if this function returns `false`.
394395
*
395396
* @property {Function} [onError]
396-
* @param {CKEDITOR.fileTools.fileLoader} loader Loaders instance.
397-
* @returns {Boolean} If `false` default behavior (remove widget) will be canceled.
397+
* @param {CKEDITOR.fileTools.fileLoader} loader Loader instance.
398+
* @returns {Boolean} If `false`, the default behavior (remove widget) will be canceled.
398399
*/
399400

400401
/**
401-
* Function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `abort`.
402+
* A function called when the {@link CKEDITOR.fileTools.fileLoader#status status} of the upload changes to `abort`.
402403
* The default behavior is to remove the widget and it can be canceled if this function returns `false`.
403404
*
404405
* @property {Function} [onAbort]
405-
* @param {CKEDITOR.fileTools.fileLoader} loader Loaders instance.
406-
* @returns {Boolean} If `false` default behavior (remove widget) will be canceled.
406+
* @param {CKEDITOR.fileTools.fileLoader} loader Loader instance.
407+
* @returns {Boolean} If `false`, the default behavior (remove widget) will be canceled.
407408
*/
408409
} );
409410

410411
editor.widgets.add( name, def );
411412
}
412413

413414
/**
414-
* Marks element which should be transformed into an upload widget.
415+
* Marks an element which should be transformed into an upload widget.
415416
*
416417
* @see CKEDITOR.fileTools.addUploadWidget
417418
*
418419
* @member CKEDITOR.fileTools
419420
* @param {CKEDITOR.dom.element} element Element to be marked.
420-
* @param {String} widgetName Name of the upload widget.
421-
* @param {Number} loaderId The id of a related {@link CKEDITOR.fileTools.fileLoader}.
421+
* @param {String} widgetName The name of the upload widget.
422+
* @param {Number} loaderId The ID of a related {@link CKEDITOR.fileTools.fileLoader}.
422423
*/
423424
function markElement( element, widgetName, loaderId ) {
424425
element.setAttributes( {
@@ -428,22 +429,22 @@
428429
}
429430

430431
/**
431-
* Binds notification to the {@link CKEDITOR.fileTools.fileLoader file loader} so the upload widget will use
432-
* notification to show the status and progress.
432+
* Binds a notification to the {@link CKEDITOR.fileTools.fileLoader file loader} so the upload widget will use
433+
* the notification to show the status and progress.
433434
* This function uses {@link CKEDITOR.plugins.notificationAggregator}, so even if multiple files are uploading
434-
* only one notification is shown. The exception are warnings, because they are shown in the separate notifications.
435-
* This notification show only progress of the upload so this method should not be used if
436-
* {@link CKEDITOR.fileTools.fileLoader#load loader.load} method was called, it works with
435+
* only one notification is shown. Warnings are an exception, because they are shown in separate notifications.
436+
* This notification shows only the progress of the upload, so this method should not be used if
437+
* the {@link CKEDITOR.fileTools.fileLoader#load loader.load} method was called. It works with
437438
* {@link CKEDITOR.fileTools.fileLoader#upload upload} and {@link CKEDITOR.fileTools.fileLoader#loadAndUpload loadAndUpload}.
438439
*
439440
* @member CKEDITOR.fileTools
440441
* @param {CKEDITOR.editor} editor The editor instance.
441-
* @param {CKEDITOR.fileTools.fileLoader} loader The fileLoader instance.
442+
* @param {CKEDITOR.fileTools.fileLoader} loader The file loader instance.
442443
*/
443444
function bindNotifications( editor, loader ) {
444445
var aggregator = editor._.uploadWidgetNotificaionAggregator;
445446

446-
// Create one notification agregator for all types of upload widgets for editor.
447+
// Create one notification agregator for all types of upload widgets for the editor.
447448
if ( !aggregator || aggregator.isFinished() ) {
448449
aggregator = editor._.uploadWidgetNotificaionAggregator = new CKEDITOR.plugins.notificationAggregator(
449450
editor, editor.lang.uploadwidget.uploadMany, editor.lang.uploadwidget.uploadOne );
@@ -488,7 +489,7 @@
488489
} );
489490
}
490491

491-
// Two plugins extends this object.
492+
// Two plugins extend this object.
492493
if ( !CKEDITOR.fileTools ) {
493494
CKEDITOR.fileTools = {};
494495
}

0 commit comments

Comments
 (0)