CKEDITOR.plugins.imagebase.imageWidgetDefinition
This is an abstract class that describes the definition of a basic image widget created by the CKEDITOR.plugins.imagebase.addImageWidget method.
Note that because the image widget is a type of a widget, this definition extends CKEDITOR.plugins.widget.definition. It adds several parts of the image and implements the basic version of the CKEDITOR.plugins.widget.definition.upcast callback.
Filtering
Properties
-
allowedContent : allowedContentRules
CKEDITOR.plugins.imagebase.imageWidgetDefinition#allowedContent
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 : String
CKEDITOR.plugins.imagebase.imageWidgetDefinition#button
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 : Object
CKEDITOR.plugins.imagebase.imageWidgetDefinition#contentForms
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 : Object
CKEDITOR.plugins.imagebase.imageWidgetDefinition#contentTransformations
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 : Function
CKEDITOR.plugins.imagebase.imageWidgetDefinition#data
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 : Object
CKEDITOR.plugins.imagebase.imageWidgetDefinition#defaults
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 : String
CKEDITOR.plugins.imagebase.imageWidgetDefinition#dialog
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 | Function
CKEDITOR.plugins.imagebase.imageWidgetDefinition#downcast
The function to be used to downcast this widget or a name of the downcast option from the downcasts object.
The downcast function will be executed in the CKEDITOR.plugins.widget context and with
widgetElement
(CKEDITOR.htmlParser.element) argument which is the widget's main element.The function may return an instance of the CKEDITOR.htmlParser.node class if the widget needs to be downcasted to a different node than the widget's main element.
-
downcasts : Object
CKEDITOR.plugins.imagebase.imageWidgetDefinition#downcasts
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 : Boolean
CKEDITOR.plugins.imagebase.imageWidgetDefinition#draggable
Whether the widget should be draggable. Defaults to
true
. If set tofalse
, the drag handler will not be displayed when hovering the widget. -
edit : Function
CKEDITOR.plugins.imagebase.imageWidgetDefinition#edit
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 : Object
CKEDITOR.plugins.imagebase.imageWidgetDefinition#editables
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]' } }
-
features : String[]
CKEDITOR.plugins.imagebase.imageWidgetDefinition#features
An array containing the names of features added to this widget's definition.
Defaults to
[]
-
getLabel : Function
CKEDITOR.plugins.imagebase.imageWidgetDefinition#getLabel
-
init : Function
CKEDITOR.plugins.imagebase.imageWidgetDefinition#init
The method executed while initializing a widget, after a widget instance is created, but before it is ready. It is executed before the first CKEDITOR.plugins.widget.data is fired so it is common to use the
init
method to populate widget data with information loaded from the DOM, like for exmaple:init: function() { this.setData( 'width', this.element.getStyle( 'width' ) ); if ( this.parts.caption.getStyle( 'display' ) != 'none' ) this.setData( 'showCaption', true ); }
-
inline : Boolean
CKEDITOR.plugins.imagebase.imageWidgetDefinition#inline
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 : Function
CKEDITOR.plugins.imagebase.imageWidgetDefinition#insert
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.
-
mask : Boolean | String
CKEDITOR.plugins.imagebase.imageWidgetDefinition#mask
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. Thestring
mask should point to the name of one of the widget parts.Note: Partial mask is available since the
4.13.0
version. -
name : String
CKEDITOR.plugins.imagebase.imageWidgetDefinition#name
Widget definition name. It is automatically set when the definition is registered.
-
parts : Object
CKEDITOR.plugins.imagebase.imageWidgetDefinition#parts
An object containing definitions of widget components (part name => CSS selector).
parts: { image: 'img', caption: 'div.caption' }
-
pathName : String
CKEDITOR.plugins.imagebase.imageWidgetDefinition#pathName
The widget name displayed in the elements path.
-
requiredContent : contentRule
CKEDITOR.plugins.imagebase.imageWidgetDefinition#requiredContent
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.4.0
styleToAllowedContentRules : Function
CKEDITOR.plugins.imagebase.imageWidgetDefinition#styleToAllowedContentRules
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 : String
CKEDITOR.plugins.imagebase.imageWidgetDefinition#styleableElements
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 fordiv
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.
-
template : String
CKEDITOR.plugins.imagebase.imageWidgetDefinition#template
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
CKEDITOR.plugins.imagebase.imageWidgetDefinition#upcast
Image widget definition overrides the CKEDITOR.plugins.widget.definition.upcast property. It is automatically set to enumerate the keys of upcasts. Avoid changes unless you know what you're doing!
-
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 : Object
CKEDITOR.plugins.imagebase.imageWidgetDefinition#upcasts
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. } );
Methods
-
since 4.13.0
getClipboardHtml() → String
CKEDITOR.plugins.imagebase.imageWidgetDefinition#getClipboardHtml
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() → feature
CKEDITOR.plugins.imagebase.imageWidgetDefinition#toFeature
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