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

CKEDITOR.fileTools

class singleton since 4.5.0
See source

Helpers to load and upload a file.

Filtering

Properties

  • since 4.9.0

    isFileUploadSupported : Boolean

    See source

    Feature detection indicating whether the current browser supports methods essential to send files over an XHR request.

Methods

  • addUploadWidget( editor, name, def )

    See source

    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

    editor : editor

    The editor instance.

    name : String

    The name of the upload widget.

    def : uploadWidgetDefinition

    Upload widget definition.

  • bindNotifications( editor, loader )

    See source

    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

    editor : editor

    The editor instance.

    loader : fileLoader

    The file loader instance.

  • getUploadUrl( config, [ type ] ) → String | null

    See source

    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

    Upload file type.

    Returns

    String | null

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

  • isTypeSupported( file, supportedTypes ) → Boolean

    See source

    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.

  • markElement( element, widgetName, loaderId )

    See source

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

    CKEDITOR.fileTools.addUploadWidget

    Parameters

    element : element

    Element to be marked.

    widgetName : String

    The name of the upload widget.

    loaderId : Number

    The ID of a related CKEDITOR.fileTools.fileLoader.