CKEDITOR.fileTools

Properties

• since 4.9.0

  isFileUploadSupported : BooleanCKEDITOR.fileTools#isFileUploadSupported

  See source

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

Methods

• addUploadWidget( editor, name, def )CKEDITOR.fileTools#addUploadWidget

  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 )CKEDITOR.fileTools#bindNotifications

  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 | nullCKEDITOR.fileTools#getUploadUrl

  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'):

  • [type]UploadUrl, e.g. CKEDITOR.config.imageUploadUrl,
  • CKEDITOR.config.uploadUrl,
  • filebrowser[uppercased type]uploadUrl, e.g. CKEDITOR.config.filebrowserImageUploadUrl,
  • CKEDITOR.config.filebrowserUploadUrl.

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

  • CKEDITOR.config.uploadUrl,
  • CKEDITOR.config.filebrowserUploadUrl.

  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 ) → BooleanCKEDITOR.fileTools#isTypeSupported

  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 )CKEDITOR.fileTools#markElement

  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.