CKEDITOR.fileTools.uploadWidgetDefinition

Properties

• additionalRequestParameters : ObjectCKEDITOR.fileTools.uploadWidgetDefinition#additionalRequestParameters

  See source

  An object containing additional data that should be passed to the function defined by loadMethod.

• allowedContent : allowedContentRulesCKEDITOR.fileTools.uploadWidgetDefinition#allowedContent

  See source

  HTML code that can be generated by this feature.

  For example a basic image feature (image button displaying the image dialog window) may allow 'img[!src,alt,width,height]'.

  During the feature activation this value is passed to CKEDITOR.filter.allow.

  Defaults to null

• button : StringCKEDITOR.fileTools.uploadWidgetDefinition#button

  See source

  The label for the widget toolbar button.

  editor.widgets.add( 'simplebox', {
      button: 'Create a simple box'
  } );
  
  editor.widgets.add( 'simplebox', {
      button: editor.lang.simplebox.title
  } );
  

• contentForms : ObjectCKEDITOR.fileTools.uploadWidgetDefinition#contentForms

  See source

  Feature content forms to be registered in the CKEDITOR.editor.filter during the feature activation.

  See CKEDITOR.filter.addContentForms for more details.

  Defaults to null

• contentTransformations : ObjectCKEDITOR.fileTools.uploadWidgetDefinition#contentTransformations

  See source

  Transformations (usually for content generated by this feature, but not necessarily) that will be registered in the CKEDITOR.editor.filter during the feature activation.

  See CKEDITOR.filter.addTransformations for more details.

  Defaults to null

• data : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#data

  See source

  If set, it will be added as the CKEDITOR.plugins.widget.data event listener. This means that it will be executed every time the widget data changes.

• defaults : ObjectCKEDITOR.fileTools.uploadWidgetDefinition#defaults

  See source

  The data object which will be used to populate the data of a newly created widget. See CKEDITOR.plugins.widget.data.

  defaults: {
      showCaption: true,
      align: 'none'
  }
  

• dialog : StringCKEDITOR.fileTools.uploadWidgetDefinition#dialog

  See source

  The name of a dialog window which will be opened on CKEDITOR.plugins.widget.edit. If not defined, then the CKEDITOR.plugins.widget.edit method will not perform any action and widget's command will insert a new widget without opening a dialog window first.

• downcast : String | FunctionCKEDITOR.fileTools.uploadWidgetDefinition#downcast

  See source

  Upload widget definition overwrites the CKEDITOR.plugins.widget.definition.downcast property. This should not be changed.

• downcasts : ObjectCKEDITOR.fileTools.uploadWidgetDefinition#downcasts

  See source

  The object containing functions which can be used to downcast this widget. Only the one pointed by the downcast property will be used.

  In most cases it is appropriate to use downcast directly, because majority of widgets have just one variant of downcasting (or none at all). However, in some cases the widget author may want to expose more than one variant and then this property may be used.

  downcasts: {
      // This downcast may transform the widget into the figure element.
      figure: function() {
          // ...
      },
      // This downcast may transform the widget into the image element with data-* attributes.
      image: function() {
          // ...
      }
  }
  
  // Then, the widget user may choose one of the downcast options when setting up his editor.
  editor.on( 'widgetDefinition', function( evt ) {
      if ( evt.data.name == 'image' )
              evt.data.downcast = 'figure';
  } );
  

• draggable : BooleanCKEDITOR.fileTools.uploadWidgetDefinition#draggable

  See source

  Whether the widget should be draggable. Defaults to true. If set to false, the drag handler will not be displayed when hovering the widget.

• edit : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#edit

  See source

  If set, it will be added as the CKEDITOR.plugins.widget.edit event listener. This means that it will be executed when a widget is being edited. See the CKEDITOR.plugins.widget.edit method.

• editables : ObjectCKEDITOR.fileTools.uploadWidgetDefinition#editables

  See source

  An object containing definitions of nested editables (editable name => CKEDITOR.plugins.widget.nestedEditable.definition). Note that editables have to be defined in the same order as they are in DOM / template. Otherwise errors will occur when nesting widgets inside each other.

  editables: {
      header: 'h1',
      content: {
          selector: 'div.content',
          allowedContent: 'p strong em; a[!href]'
      }
  }
  

• fileToElement : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#fileToElement

  See source

  If this property is defined, paste listener is created to transform the pasted file into an HTML element. It creates an HTML element which will be then transformed into an upload widget. It is only called for supported files. If multiple files were pasted, this function will be called for each file of a supported type.

  Parameters

  file : Blob

  A pasted file to load or upload.

  getLabel : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#getLabel

  See source

  The function used to obtain an accessibility label for the widget. It might be used to make the widget labels as precise as possible, since it has access to the widget instance.

  If not specified, the default implementation will use the pathName or the main element tag name.

  init : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#init

  See source

  Upload widget definition overwrites the CKEDITOR.plugins.widget.definition.init property. If you want to add some code in the init callback remember to call the base function.

  inline : BooleanCKEDITOR.fileTools.uploadWidgetDefinition#inline

  See source

  If set to true/false, it will force the widget to be either an inline or a block widget. If not set, the widget type will be determined from the widget element.

  Widget type influences whether a block (<div>) or an inline (<span>) element is used for the wrapper.

  insert : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#insert

  See source

  The method to be executed when the widget's command is executed in order to insert a new widget (widget of this type is not focused). If not defined, then the default action will be performed which means that:

  • An instance of the widget will be created in a detached document fragment,
  • The CKEDITOR.plugins.widget.edit method will be called to trigger widget editing,
  • The widget element will be inserted into DOM.

  Parameters

  options : Object

  Options object added in 4.11.0.

  loadMethod : StringCKEDITOR.fileTools.uploadWidgetDefinition#loadMethod

  See source

  The type of loading operation that should be executed as a result of pasting a file. Possible options are:

  • 'loadAndUpload' – Default behavior. The CKEDITOR.fileTools.fileLoader.loadAndUpload method will be executed, the file will be loaded first and uploaded immediately after loading is done.
  • 'load' – The CKEDITOR.fileTools.fileLoader.load method will be executed. This loading type should be used if you only want to load file data without uploading it.
  • 'upload' – The CKEDITOR.fileTools.fileLoader.upload method will be executed, the file will be uploaded without loading it to memory. This loading type should be used if you want to upload a big file, otherwise you can get an "out of memory" error.

  Defaults to loadAndUpload

  loaderType : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#loaderType

  See source

  Loader type that should be used for creating file tools requests.

  mask : Boolean | StringCKEDITOR.fileTools.uploadWidgetDefinition#mask

  See source

  If set to true, the widget's element will be covered with a transparent mask. This will prevent its content from being clickable, which matters in case of special elements like embedded iframes that generate a separate "context".

  If the value is a string type, then the partial mask covering only the given widget part is created instead. The string mask should point to the name of one of the widget parts.

  Note: Partial mask is available since the 4.13.0 version.

  name : StringCKEDITOR.fileTools.uploadWidgetDefinition#name

  See source

  Widget definition name. It is automatically set when the definition is registered.

  onAbort : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#onAbort

  See source

  A function called when the status of the upload changes to abort. The default behavior is to remove the widget and it can be canceled if this function returns false.

  Parameters

  loader : fileLoader

  Loader instance.

  onError : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#onError

  See source

  A function called when the status of the upload changes to error. The default behavior is to remove the widget and it can be canceled if this function returns false.

  Parameters

  loader : fileLoader

  Loader instance.

  onLoaded : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#onLoaded

  See source

  A function called when the status of the upload changes to loaded.

  Parameters

  loader : fileLoader

  Loader instance.

  onLoading : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#onLoading

  See source

  A function called when the status of the upload changes to loading.

  Parameters

  loader : fileLoader

  Loader instance.

  onUploaded : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#onUploaded

  See source

  A function called when the status of the upload changes to uploaded. At that point the upload is done and the upload widget should be replaced with the final HTML using the replaceWith method.

  Parameters

  loader : fileLoader

  Loader instance.

  onUploading : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#onUploading

  See source

  A function called when the status of the upload changes to uploading.

  Parameters

  loader : fileLoader

  Loader instance.

  parts : ObjectCKEDITOR.fileTools.uploadWidgetDefinition#parts

  See source

  An object containing definitions of widget components (part name => CSS selector).

  parts: {
      image: 'img',
      caption: 'div.caption'
  }
  

  pathName : StringCKEDITOR.fileTools.uploadWidgetDefinition#pathName

  See source

  The widget name displayed in the elements path.

  replaceWith : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#replaceWith

  See source

  Replaces the upload widget with the final HTML. This method should be called when the upload is done, usually in the onUploaded callback.

  Parameters

  data : String

  HTML to replace the upload widget.

  [ mode ] : String

  See CKEDITOR.editor.insertHtml's modes.

  Defaults to 'html'

  requiredContent : contentRuleCKEDITOR.fileTools.uploadWidgetDefinition#requiredContent

  See source

  Minimal HTML code that this feature must be allowed to generate in order to work.

  For example a basic image feature (image button displaying the image dialog window) needs 'img[src,alt]' in order to be activated.

  During the feature validation this value is passed to CKEDITOR.filter.check.

  If this value is not provided, a feature will be always activated.

  Defaults to null

  since 4.8.0

  skipNotifications : BooleanCKEDITOR.fileTools.uploadWidgetDefinition#skipNotifications

  See source

  Indicates whether default notification handling should be skipped.

  By default upload widget will use Notification plugin to provide feedback for upload progress and eventual success / error message.

  Defaults to false

  since 4.4.0

  styleToAllowedContentRules : FunctionCKEDITOR.fileTools.uploadWidgetDefinition#styleToAllowedContentRules

  See source

  Function transforming custom widget's CKEDITOR.style instance into CKEDITOR.filter.allowedContentRules. It may be used when a static styleableElements property is not enough to inform the CKEDITOR.filter what HTML features should be enabled when allowing the given style.

  In most cases, when style's classes just have to be added to element name(s) used by the widget element, it is recommended to use simpler styleableElements property.

  In order to get parsed classes from the style definition you can use CKEDITOR.style.customHandlers.widget.getClassesArray.

  For example, if you want to use the object format of allowed content rules, to specify match validator, your implementation could look like this:

  editor.widgets.add( 'customWidget', {
      // ...
  
      styleToAllowedContentRules: funciton( style ) {
          // Retrieve classes defined in the style.
          var classes = style.getClassesArray();
  
          // Do something crazy - for example return allowed content rules in object format,
          // with custom match property and propertiesOnly flag.
          return {
              h1: {
                  match: isWidgetElement,
                  propertiesOnly: true,
                  classes: classes
              }
          };
      }
  } );
  

  Parameters

  style : widget

  The style to be transformed.

  since 4.4.0

  styleableElements : StringCKEDITOR.fileTools.uploadWidgetDefinition#styleableElements

  See source

  Names of element(s) (separated by spaces) for which the CKEDITOR.filter should allow classes defined in the widget styles. For example, if your widget is upcasted from a simple <div> element, then in order to make it styleable you can set:

  editor.widgets.add( 'customWidget', {
      upcast: function( element ) {
          return element.name == 'div';
      },
  
      // ...
  
      styleableElements: 'div'
  } );
  

  Then, when the following style is defined:

  {
      name: 'Thick border', type: 'widget', widget: 'customWidget',
      attributes: { 'class': 'thickBorder' }
  }
  

  a rule allowing the thickBorder class for div elements will be registered in the CKEDITOR.filter.

  If you need to have more freedom when transforming widget style to allowed content rules, you can use the styleToAllowedContentRules callback.

  supportedTypes : RegExpCKEDITOR.fileTools.uploadWidgetDefinition#supportedTypes

  See source

  Regular expression to check if the file type is supported by this widget. If not defined, all files will be handled.

  template : StringCKEDITOR.fileTools.uploadWidgetDefinition#template

  See source

  The template which will be used to create a new widget element (when the widget's command is executed). This string is populated with default values by using the CKEDITOR.template format. Therefore it has to be a valid CKEDITOR.template argument.

  upcast : String | FunctionCKEDITOR.fileTools.uploadWidgetDefinition#upcast

  See source

  The function to be used to upcast an element to this widget or a comma-separated list of upcast methods from the upcasts object.

  The upcast function is not executed in the widget context (because the widget does not exist yet), however, it is executed in the widget's definition context. Two arguments are passed to the upcast function:

  • element (CKEDITOR.htmlParser.element) – The element to be checked.
  • data (Object) – The object which can be extended with data which will then be passed to the widget.

  An element will be upcasted if a function returned true or an instance of a CKEDITOR.htmlParser.element if upcasting meant DOM structure changes (in this case the widget will be initialized on the returned element).

  since 4.5.0

  upcastPriority : NumberCKEDITOR.fileTools.uploadWidgetDefinition#upcastPriority

  See source

  The upcast method(s) priority. The upcast with a lower priority number will be called before the one with a higher number. The default priority is 10.

  Defaults to 10

  upcasts : ObjectCKEDITOR.fileTools.uploadWidgetDefinition#upcasts

  See source

  The object containing functions which can be used to upcast this widget. Only those pointed by the upcast property will be used.

  In most cases it is appropriate to use upcast directly, because majority of widgets need just one method. However, in some cases the widget author may want to expose more than one variant and then this property may be used.

  upcasts: {
      // This function may upcast only figure elements.
      figure: function() {
          // ...
      },
      // This function may upcast only image elements.
      image: function() {
          // ...
      },
      // More variants...
  }
  
  // Then, widget user may choose which upcast methods will be enabled.
  editor.on( 'widgetDefinition', function( evt ) {
      if ( evt.data.name == 'image' )
              evt.data.upcast = 'figure,image'; // Use both methods.
  } );
  

  uploadUrl : StringCKEDITOR.fileTools.uploadWidgetDefinition#uploadUrl

  See source

  The URL to which the file will be uploaded. It should be taken from the configuration using CKEDITOR.fileTools.getUploadUrl.

  Methods

  • since 4.13.0

    getClipboardHtml() → StringCKEDITOR.fileTools.uploadWidgetDefinition#getClipboardHtml

    See source

    Customizes widget HTML copied to the clipboard during copy, cut and drop operations.

    If not set, the current widget HTML will be used instead.

    Note: This method will overwrite the HTML for the whole widget, including any nested widgets.

    Returns

    String

    Widget HTML.

    toFeature() → featureCKEDITOR.fileTools.uploadWidgetDefinition#toFeature

    See source

    Returns a feature that this feature needs to register.

    In some cases, during activation, one feature may need to register another feature. For example a CKEDITOR.ui.button often registers a related command. See CKEDITOR.ui.button.toFeature.

    This method is executed when a feature is passed to the CKEDITOR.editor.addFeature.

    Returns

    feature

    private

    _getLoader() → fileLoader | nullCKEDITOR.fileTools.uploadWidgetDefinition#_getLoader

    See source

    Returns

    fileLoader | null

    The loader associated with this widget instance or null if not found.