CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 4/API
Class

CKEDITOR.fileTools.fileLoader

classsince 4.5.0
See source

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.

Filtering

Properties

  • readonly

    data : String

    See source

    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.

  • readonly

    file : Blob

    See source

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

  • readonly

    fileName : String

    See source

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

  • readonly

    id : Number

    See source

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

  • readonly

    loaded : Number

    See source

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

  • readonly

    message : String

    See source

    The error message or additional information received from the server.

  • readonly

    reader : FileReader

    See source

    Native FileReader reference used to load the file.

  • readonly

    responseData : Object

    See source

    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.

  • status : String

    See source

    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.

  • readonly

    total : Number

    See source

    The total file size in bytes.

  • readonly

    uploadTotal : Number

    See source

    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 );
        }
    });

  • readonly

    uploadUrl : String

    See source

    The target of the upload.

  • readonly

    uploaded : Number

    See source

    The number of uploaded bytes.

  • readonly

    url : String

    See source

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

  • readonly

    xhr : XMLHttpRequest

    See source

    Native XMLHttpRequest reference used to upload the file.

Static properties

Methods