CKEditor 4 Documentation

CKEDITOR.fileTools.fileLoader

Mixins

Files

The FileLoader class is a wrapper which handles two file operations: loading the content of the file stored on the user's device into the memory and uploading the file to the server.

There are two possible ways to crate a FileLoader instance: with a Blob (e.g. acquired from the CKEDITOR.plugins.clipboard.dataTransfer.getFile method) or with data as a Base64 string. Note that if the constructor gets the data as a Base64 string, there is no need to load the data, the data is already loaded.

The FileLoader is created for a single load and upload process so if you abort the process, you need to create a new FileLoader.

All process parameters are stored in public properties.

FileLoader implements events so you can listen to them to react to changes. There are two types of events: events to notify the listeners about changes and an event that lets the listeners synchronize with current status.

The first group of events contains loading, loaded, uploading, uploaded, error and abort. These events are called only once, when the status changes.

The second type is the update event. It is fired every time the status changes, the progress changes or the update method is called. Is is created to synchronize the visual representation of the loader with its status. For example if the dialog window shows the upload progress, it should be refreshed on the update listener. Then when the user closes and reopens this dialog, the update method should be called to refresh the progress.

Default request and response formats will work with CKFinder 2.4.3 and above. If you need a custom request or response handling you need to overwrite the default behavior using the CKEDITOR.editor.fileUploadRequest and CKEDITOR.editor.fileUploadResponse events. For more information see their documentation.

To create a FileLoader instance, use the CKEDITOR.fileTools.uploadRepository class.

Here is a simple FileLoader usage example:

editor.on( 'paste', function( evt ) {
    for ( var i = 0; i < evt.data.dataTransfer.getFilesCount(); i++ ) {
        var file = evt.data.dataTransfer.getFile( i );

        if ( CKEDITOR.fileTools.isTypeSupported( file, /image\/png/ ) ) {
            var loader = editor.uploadRepository.create( file );

            loader.on( 'update', function() {
                document.getElementById( 'uploadProgress' ).innerHTML = loader.status;
            } );

            loader.on( 'error', function() {
                alert( 'Error!' );
            } );

            loader.loadAndUpload( 'http://upload.url/' );

            evt.data.dataValue += 'loading...'
        }
    }
} );

Note that FileLoader uses the native file API which is supported since Internet Explorer 10.

Available since: 4.5

Defined By

Properties

CKEDITOR.fileTools.fileLoader
view source
: Stringreadonly
String data encoded with Base64. ...

String data encoded with Base64. If the FileLoader is created with a Base64 string, the data is that string. If a file was passed to the constructor, the data is null until loading is completed.

CKEDITOR.fileTools.fileLoader
view source
: Blobreadonly
File object which represents the handled file. ...

File object which represents the handled file. This property is set for both constructor options (file or data).

CKEDITOR.fileTools.fileLoader
view source
: Stringreadonly
The name of the file. ...

The name of the file. If there is no file name, it is created by using the CKEDITOR.config.fileTools_defaultFileName option.

CKEDITOR.fileTools.fileLoader
view source
: Numberreadonly
If FileLoader was created using CKEDITOR.fileTools.uploadRepository, it gets an identifier which is stored in this pr...

If FileLoader was created using CKEDITOR.fileTools.uploadRepository, it gets an identifier which is stored in this property.

CKEDITOR.fileTools.fileLoader
view source
: Numberreadonly
The number of loaded bytes. ...

The number of loaded bytes. If the FileLoader was created with a data string, the loaded value equals the total value.

CKEDITOR.fileTools.fileLoader
view source
: Stringreadonly

The error message or additional information received from the server.

The error message or additional information received from the server.

CKEDITOR.fileTools.fileLoader
view source
: FileReaderreadonly

Native FileReader reference used to load the file.

Native FileReader reference used to load the file.

CKEDITOR.fileTools.fileLoader
view source
: Objectreadonly
All data received in the response from the server. ...

All data received in the response from the server. If the server returns additional data, it will be available in this property.

It contains all data set in the CKEDITOR.editor.fileUploadResponse event listener.

CKEDITOR.fileTools.fileLoader
view source
: String
The loader status. ...

The loader status. Possible values:

  • created – The loader was created, but neither load nor upload started.
  • loading – The file is being loaded from the user's storage.
  • loaded – The file was loaded, the process is finished.
  • uploading – The file is being uploaded to the server.
  • uploaded – The file was uploaded, the process is finished.
  • error – The process stops because of an error, more details are available in the message property.
  • abort – The process was stopped by the user.
CKEDITOR.fileTools.fileLoader
view source
: Numberreadonly

The total file size in bytes.

The total file size in bytes.

CKEDITOR.fileTools.fileLoader
view source
: Numberreadonly
The total size of upload data in bytes. ...

The total size of upload data in bytes. If the xhr.upload object is present, this value will indicate the total size of the request payload, not only the file size itself. If the xhr.upload object is not available and the real upload size cannot be obtained, this value will be equal to total. It has a null value until the upload size is known.

    loader.on( 'update', function() {
        // Wait till uploadTotal is present.
        if ( loader.uploadTotal ) {
            console.log( 'uploadTotal: ' + loader.uploadTotal );
        }
    });
CKEDITOR.fileTools.fileLoader
view source
: Stringreadonly

The target of the upload.

The target of the upload.

CKEDITOR.fileTools.fileLoader
view source
: Numberreadonly

The number of uploaded bytes.

The number of uploaded bytes.

CKEDITOR.fileTools.fileLoader
view source
: Stringreadonly

The URL to the file when it is uploaded or received from the server.

The URL to the file when it is uploaded or received from the server.

CKEDITOR.fileTools.fileLoader
view source
: XMLHttpRequestreadonly

Native XMLHttpRequest reference used to upload the file.

Native XMLHttpRequest reference used to upload the file.

Defined By

Methods

CKEDITOR.fileTools.fileLoader
view source
new( editor, fileOrData, [fileName] ) : CKEDITOR.fileTools.fileLoader
Creates an instance of the class and sets initial values for all properties. ...

Creates an instance of the class and sets initial values for all properties.

Parameters

  • editor : CKEDITOR.editor

    The editor instance. Used only to get language data.

  • fileOrData : Blob/String

    A blob object or a data string encoded with Base64.

  • fileName : String (optional)

    The file name. If not set and the second parameter is a file, then its name will be used. If not set and the second parameter is a Base64 data string, then the file name will be created based on the CKEDITOR.config.fileTools_defaultFileName option.

Returns

Overrides: CKEDITOR.event.constructor

CKEDITOR.fileTools.fileLoader
view source
( )
Aborts the process. ...

Aborts the process.

This method has a different behavior depending on the current status.

  • If the status is loading or uploading, current operation will be aborted.
  • If the status is created, loading or uploading, the status will be changed to abort and the abort event will be called.
  • If the status is loaded, uploaded, error or abort, this method will do nothing.
CKEDITOR.fileTools.fileLoader
view source
( xhr )private
Attaches listeners to the XML HTTP request object. ...

Attaches listeners to the XML HTTP request object.

Parameters

  • xhr : XMLHttpRequest

    XML HTTP request object.

Register event handler under the capturing stage on supported target. ...

Register event handler under the capturing stage on supported target.

CKEDITOR.fileTools.fileLoader
view source
( newStatus )private
Changes status to the new status, updates the abort method if needed and fires two events: new status and update. ...

Changes status to the new status, updates the abort method if needed and fires two events: new status and update.

Parameters

  • newStatus : String

    New status to be set.

Predefine some intrinsic properties on a specific event name. ...

Predefine some intrinsic properties on a specific event name.

Parameters

  • name : String

    The event name

  • meta : Object
    • errorProof : (optional)

      Whether the event firing should catch error thrown from a per listener call.

      Defaults to: false

( eventName, [data], [editor] ) : Boolean/Object
Fires an specific event in the object. ...

Fires an specific event in the object. All registered listeners are called at this point.

someObject.on( 'someEvent', function() { ... } );
someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );             // Both listeners are called.

someObject.on( 'someEvent', function( event ) {
    alert( event.data );                    // 'Example'
} );
someObject.fire( 'someEvent', 'Example' );

Parameters

Returns

  • Boolean/Object

    A boolean indicating that the event is to be canceled, or data returned by one of the listeners.

( eventName, [data], [editor] ) : Boolean/Object
Fires an specific event in the object, releasing all listeners registered to that event. ...

Fires an specific event in the object, releasing all listeners registered to that event. The same listeners are not called again on successive calls of it or of fire.

someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );         // Above listener called.
someObject.fireOnce( 'someEvent' );     // Above listener called.
someObject.fire( 'someEvent' );         // No listeners called.

Parameters

Returns

  • Boolean/Object

    A booloan indicating that the event is to be canceled, or data returned by one of the listeners.

Checks if there is any listener registered to a given event. ...

Checks if there is any listener registered to a given event.

var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
alert( someObject.hasListeners( 'someEvent' ) );    // true
alert( someObject.hasListeners( 'noEvent' ) );      // false

Parameters

  • eventName : String

    The event name.

Returns

  • Boolean
CKEDITOR.fileTools.fileLoader
view source
( ) : Boolean
Returns true if the loading and uploading finished (successfully or not), so the status is loaded, uploaded, error or...

Returns true if the loading and uploading finished (successfully or not), so the status is loaded, uploaded, error or abort.

Returns

  • Boolean

    true if the loading and uploading finished.

CKEDITOR.fileTools.fileLoader
view source
( )
Loads a file from the storage on the user's device to the data attribute. ...

Loads a file from the storage on the user's device to the data attribute.

The order of the statuses for a successful load is:

  • created,
  • loading,
  • loaded.
CKEDITOR.fileTools.fileLoader
view source
( url, [additionalRequestParameters] )
Loads a file from the storage on the user's device to the data attribute and uploads it to the server. ...

Loads a file from the storage on the user's device to the data attribute and uploads it to the server.

The order of statuses for a successful load and upload is:

  • created,
  • loading,
  • uploading,
  • uploaded.

Parameters

  • url : String

    The upload URL.

  • additionalRequestParameters : Object (optional)

    Additional parameters that would be passed to the CKEDITOR.editor.fileUploadRequest event.

( eventName, listenerFunction, [scopeObj], [listenerData], [priority] ) : Object
Registers a listener to a specific event in the current object. ...

Registers a listener to a specific event in the current object.

someObject.on( 'someEvent', function() {
    alert( this == someObject );        // true
} );

someObject.on( 'someEvent', function() {
    alert( this == anotherObject );     // true
}, anotherObject );

someObject.on( 'someEvent', function( event ) {
    alert( event.listenerData );        // 'Example'
}, null, 'Example' );

someObject.on( 'someEvent', function() { ... } );                       // 2nd called
someObject.on( 'someEvent', function() { ... }, null, null, 100 );      // 3rd called
someObject.on( 'someEvent', function() { ... }, null, null, 1 );        // 1st called

Parameters

  • eventName : String

    The event name to which listen.

  • listenerFunction : Function

    The function listening to the event. A single CKEDITOR.eventInfo object instanced is passed to this function containing all the event data.

  • scopeObj : Object (optional)

    The object used to scope the listener call (the this object). If omitted, the current object is used.

  • listenerData : Object (optional)

    Data to be sent as the CKEDITOR.eventInfo.listenerData when calling the listener.

  • priority : Number (optional)

    The listener priority. Lower priority listeners are called first. Listeners with the same priority value are called in registration order.

    Defaults to: 10

Returns

  • Object

    An object containing the removeListener function, which can be used to remove the listener at any time.

Similiar with on but the listener will be called only once upon the next event firing. ...

Similiar with on but the listener will be called only once upon the next event firing.

CKEDITOR.event.on

Remove all existing listeners on this object, for cleanup purpose. ...

Remove all existing listeners on this object, for cleanup purpose.

( eventName, listenerFunction )
Unregisters a listener function from being called at the specified event. ...

Unregisters a listener function from being called at the specified event. No errors are thrown if the listener has not been registered previously.

var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener called.
someObject.removeListener( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener not called.

Parameters

  • eventName : String

    The event name.

  • listenerFunction : Function

    The listener function to unregister.

CKEDITOR.fileTools.fileLoader
view source
( )
Updates the state of the FileLoader listeners. ...

Updates the state of the FileLoader listeners. This method should be called if the state of the visual representation of the upload process is out of synchronization and needs to be refreshed (e.g. because of an undo operation or because the dialog window with the upload is closed and reopened). Fires the update event.

CKEDITOR.fileTools.fileLoader
view source
( url, [additionalRequestParameters] )
Uploads a file to the server. ...

Uploads a file to the server.

The order of the statuses for a successful upload is:

  • created,
  • uploading,
  • uploaded.

Parameters

Defined By

Events

CKEDITOR.fileTools.fileLoader
view source
( evt )
Event fired when the status changes to abort. ...

Event fired when the status changes to abort. It will be fired once for the FileLoader.

Parameters

CKEDITOR.fileTools.fileLoader
view source
( evt )
Event fired when the status changes to error. ...

Event fired when the status changes to error. It will be fired once for the FileLoader.

Parameters

CKEDITOR.fileTools.fileLoader
view source
( evt )
Event fired when the status changes to loaded. ...

Event fired when the status changes to loaded. It will be fired once for the FileLoader.

Parameters

CKEDITOR.fileTools.fileLoader
view source
( evt )
Event fired when the status changes to loading. ...

Event fired when the status changes to loading. It will be fired once for the FileLoader.

Parameters

CKEDITOR.fileTools.fileLoader
view source
( evt )
Event fired every time the FileLoader status or progress changes or the update method is called. ...

Event fired every time the FileLoader status or progress changes or the update method is called. This event was designed to allow showing the visualization of the progress and refresh that visualization every time the status changes. Note that multiple update events may be fired with the same status.

Parameters

CKEDITOR.fileTools.fileLoader
view source
( evt )
Event fired when the status changes to uploaded. ...

Event fired when the status changes to uploaded. It will be fired once for the FileLoader.

Parameters

CKEDITOR.fileTools.fileLoader
view source
( evt )
Event fired when the status changes to uploading. ...

Event fired when the status changes to uploading. It will be fired once for the FileLoader.

Parameters