CKEditor 4 Documentation

CKEDITOR.fileTools

Files

Helpers to load and upload a file.

Available since: 4.5

Defined By

Methods

CKEDITOR.fileTools
view source
( editor, name, def )
This function creates an upload widget — a placeholder to show the progress of an upload. ...

This function creates an upload widget — a placeholder to show the progress of an upload. The upload widget is based on its definition. The addUploadWidget method also creates a paste event, if the fileToElement method is defined. This event helps in handling pasted files, as it will automatically check if the files were pasted and mark them to be uploaded.

The upload widget helps to handle content that is uploaded asynchronously inside the editor. It solves issues such as: editing during upload, undo manager integration, getting data, removing or copying uploaded element.

To create an upload widget you need to define two transformation methods:

  • The fileToElement method which will be called on paste and transform a file into a placeholder.
  • The onUploaded method with the replaceWith method which will be called to replace the upload placeholder with the final HTML when the upload is done. If you want to show more information about the progress you can also define the onLoading and onUploading methods.

The simplest uploading widget which uploads a file and creates a link to it may look like this:

    CKEDITOR.fileTools.addUploadWidget( editor, 'uploadfile', {
    uploadUrl: CKEDITOR.fileTools.getUploadUrl( editor.config ),

    fileToElement: function( file ) {
        var a = new CKEDITOR.dom.element( 'a' );
        a.setText( file.name );
        a.setAttribute( 'href', '#' );
        return a;
    },

    onUploaded: function( upload ) {
        this.replaceWith( '<a href="' + upload.url + '" target="_blank">' + upload.fileName + '</a>' );
    }
} );

The upload widget uses CKEDITOR.fileTools.fileLoader as a helper to upload the file. A CKEDITOR.fileTools.fileLoader instance is created when the file is pasted and a proper method is called — by default it is the CKEDITOR.fileTools.fileLoader.loadAndUpload method. If you want to only use the load or upload, you can use the loadMethod property.

Note that if you want to handle a big file, e.g. a video, you may need to use upload instead of loadAndUpload because the file may be too big to load it to memory at once.

If you do not upload the file, you need to define onLoaded instead of onUploaded. For example, if you want to read the content of the file:

CKEDITOR.fileTools.addUploadWidget( editor, 'fileReader', {
    loadMethod: 'load',
    supportedTypes: /text\/(plain|html)/,

    fileToElement: function( file ) {
        var el = new CKEDITOR.dom.element( 'span' );
        el.setText( '...' );
        return el;
    },

    onLoaded: function( loader ) {
        this.replaceWith( atob( loader.data.split( ',' )[ 1 ] ) );
    }
} );

If you need to pass additional data to the request, you can do this using the additionalRequestParameters property. That data is then passed to the upload method defined by CKEDITOR.fileTools.uploadWidgetDefinition.loadMethod, and to the CKEDITOR.editor.fileUploadRequest event (as part of the requestData property). The syntax of that parameter is compatible with the CKEDITOR.editor.fileUploadRequest requestData property.

CKEDITOR.fileTools.addUploadWidget( editor, 'uploadFile', {
    additionalRequestParameters: {
        foo: 'bar'
    },

    fileToElement: function( file ) {
        var el = new CKEDITOR.dom.element( 'span' );
        el.setText( '...' );
        return el;
    },

    onUploaded: function( upload ) {
        this.replaceWith( '<a href="' + upload.url + '" target="_blank">' + upload.fileName + '</a>' );
    }
} );

If you need custom paste handling, you need to mark the pasted element to be changed into an upload widget using markElement. For example, instead of the fileToElement helper from the example above, a paste listener can be created manually:

editor.on( 'paste', function( evt ) {
    var file, i, el, loader;

    for ( i = 0; i < evt.data.dataTransfer.getFilesCount(); i++ ) {
        file = evt.data.dataTransfer.getFile( i );

        if ( CKEDITOR.fileTools.isTypeSupported( file, /text\/(plain|html)/ ) ) {
            el = new CKEDITOR.dom.element( 'span' ),
            loader = editor.uploadRepository.create( file );

            el.setText( '...' );

            loader.load();

            CKEDITOR.fileTools.markElement( el, 'filereader', loader.id );

            evt.data.dataValue += el.getOuterHtml();
        }
    }
} );

Note that you can bind notifications to the upload widget on paste using the bindNotifications method, so notifications will automatically show the progress of the upload. Because this method shows notifications about upload, do not use it if you only load (and not upload) a file.

editor.on( 'paste', function( evt ) {
    var file, i, el, loader;

    for ( i = 0; i < evt.data.dataTransfer.getFilesCount(); i++ ) {
        file = evt.data.dataTransfer.getFile( i );

        if ( CKEDITOR.fileTools.isTypeSupported( file, /text\/pdf/ ) ) {
            el = new CKEDITOR.dom.element( 'span' ),
            loader = editor.uploadRepository.create( file );

            el.setText( '...' );

            loader.upload();

            CKEDITOR.fileTools.markElement( el, 'pdfuploader', loader.id );

            CKEDITOR.fileTools.bindNotifications( editor, loader );

            evt.data.dataValue += el.getOuterHtml();
        }
    }
} );

Parameters

CKEDITOR.fileTools
view source
( editor, loader )
Binds a notification to the file loader so the upload widget will use the notification to show the status and progress. ...

Binds a notification to the file loader so the upload widget will use the notification to show the status and progress. This function uses CKEDITOR.plugins.notificationAggregator, so even if multiple files are uploading only one notification is shown. Warnings are an exception, because they are shown in separate notifications. This notification shows only the progress of the upload, so this method should not be used if the loader.load method was called. It works with upload and loadAndUpload.

Parameters

CKEDITOR.fileTools
view source
( config, [type] ) : String/null
Gets the upload URL from the configuration. ...

Gets the upload URL from the configuration. Because of backward compatibility the URL can be set using multiple configuration options.

If the type is defined, then four configuration options will be checked in the following order (examples for type='image'):

If the type is not defined, two configuration options will be checked:

filebrowser[type]uploadUrl and filebrowserUploadUrl are checked for backward compatibility with the filebrowser plugin.

For both filebrowser[type]uploadUrl and filebrowserUploadUrl &responseType=json is added to the end of the URL.

Parameters

  • config : Object

    The configuration file.

  • type : String (optional)

    Upload file type.

Returns

  • String/null

    Upload URL or null if none of the configuration options were defined.

CKEDITOR.fileTools
view source
( file, supportedTypes ) : Boolean
Checks if the MIME type of the given file is supported. ...

Checks if the MIME type of the given file is supported.

    CKEDITOR.fileTools.isTypeSupported( { type: 'image/png' }, /image\/(png|jpeg)/ ); // true
    CKEDITOR.fileTools.isTypeSupported( { type: 'image/png' }, /image\/(gif|jpeg)/ ); // false

Parameters

  • file : Blob

    The file to check.

  • supportedTypes : RegExp

    A regular expression to check the MIME type of the file.

Returns

  • Boolean

    true if the file type is supported.

CKEDITOR.fileTools
view source
( element, widgetName, loaderId )
Marks an element which should be transformed into an upload widget. ...

Marks an element which should be transformed into an upload widget.

CKEDITOR.fileTools.addUploadWidget

Parameters