Home/CKEditor 4/API

CKEDITOR.plugins.embedBase.baseDefinition

class abstract

Hierarchy

definition
- baseDefinition

Mixes

feature

See source

An embed widget base definition. It predefines a few widget definition properties such as mask, template and pathName and adds methods related to content embedding.

To create a base definition use the CKEDITOR.plugins.embedBase.createWidgetBaseDefinition method.

Note: For easier browsing of this class's API you can hide inherited method using the "Show" drop-down on the right-hand side.

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

allowedContent : allowedContentRules

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 : String`

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 : Object

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 : Object

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 : Function

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 : Object
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 : String

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 | Function

See source
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`

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 : Boolean

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 : Function

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 : Object
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]'
    }
}
```
getLabel : Function

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 : Function
See source
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

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 : Function
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.
mask : Boolean | String

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.
inherited
name : String

See source
Widget definition name. It is automatically set when the definition is registered.
parts : Object
See source
An object containing definitions of widget components (part name => CSS selector).
```
parts: {
    image: 'img',
    caption: 'div.caption'
}
```
pathName : String

See source
The widget name displayed in the elements path.
providerUrl : template
See source
The template used to generate the URL of the content provider. Content provider is a service which the embed widget will request in order to get an oEmbed response that can be transformed into content which can be embedded in the editor.

Example content providers are:
- Iframely,
- Noembed.
Both Iframely and Noembed are proxy services which support JSONP requests, hence they are not limited by the same-origin policy. Unfortunately, usually oEmbed services exposed by real content providers like YouTube or Twitter do not support XHR with CORS or do not support oEmbed at all which makes it impossible or hard to get such content to be embedded in the editor. This problem is solved by proxy content providers like Iframely and Noembed.

This property must be defined after creating an embed widget base definition.

By default two values are passed to the template:
- {url} – The URL of the resource to be embedded.
- {callback} – The JSONP callback to be executed.
Example value:
```
widgetDefinition.providerUrl = new CKEDITOR.template(
    '//ckeditor.iframe.ly/api/oembed?url={url}&callback={callback}'
);
```
requiredContent : contentRule

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.4.0
styleToAllowedContentRules : Function
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 : String
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.
template : String

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 | Function
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 : Number

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 : Object`

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.
} );

urlRegExp : RegExp
See source
A regular expression to pre-validate URLs.

See:
- [https://iframely.com/docs/providers],
- isUrlValid.
Defaults to /^((https?:)?\/\/|www\.)/i
private
_cache : Object

See source
Response cache. This cache object will be shared between all instances of this widget.

Defaults to {}

Methods

since 4.13.0
getClipboardHtml() → String

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.
getErrorMessage( messageTypeOrMessage, [ url ], [ suffix ] ) → String
See source
Generates an error message based on the message type (with a possible suffix) or the custom message template.

This method is used when showing a notification or an alert (in a dialog) about an error. Usually it is used with an error type which is a string from the editor.lang.embedbase object.

There are two error types available at the moment: 'unsupportedUrl' and 'fetchingFailed'. Additionally, both can be suffixed with 'Given'. See the language entries to see the difference. Inside the dialog this method is used with a suffix and to generate a notification message it is used without a suffix.

Additionally, a custom message may be passed and just like language entries, it can use the {url} placeholder.

While handling the response you can set an error message or its type. It will be passed to this method later.
```
widget.on( 'handleResponse', function( evt ) {
    if ( evt.data.response.type != 'rich' ) {
        evt.data.errorMessage = '{url} cannot be embedded. Only rich type is supported.';
        evt.cancel();

        // Or:
        evt.data.errorMessage = 'unsupportedUrl.';
        evt.cancel();
    }
} );
```
If you need to display your own error:
```
editor.showNotification(
    widget.getErrorMessage( '{url} cannot be embedded. Only rich type is supported.', wrongUrl )
);
```
Or with a message type:
```
editor.showNotification(
    widget.getErrorMessage( 'unsupportedUrl', wrongUrl )
);
```
Parameters

messageTypeOrMessage : String

[ url ] : String

[ suffix ] : String

Returns

String
isUrlValid( url ) → Boolean

See source
Checks whether the URL is valid. Usually the content provider makes the final validation as only the provider knows what kind of URLs are accepted. However, to give the user some immediate feedback a synchronous validation is performed using the urlRegExp pattern and the validateUrl event.

Parameters

url : String

The URL to check.

Returns

Boolean

Whether the URL is valid (supported).
loadContent( url, opts ) → request
See source
Loads content for a given resource URL by requesting the provider.

Usually widgets are controlled by the CKEDITOR.plugins.widget.setData method. However, loading content is an asynchronous operation due to client-server communication, and it would not be possible to pass callbacks to the CKEDITOR.plugins.widget.setData method so this new method is defined for embed widgets.

This method fires two events that allow to customize widget behavior without changing its code:
- sendRequest,
- handleResponse (if the request was successful).
Note: This method is always asynchronous, even if the cache was hit.

Example usage:
```
var url = 'https://twitter.com/reinmarpl/status/573118615274315776';
widget.loadContent( url, {
    callback: function() {
        // Success. It is a good time to save a snapshot.
        editor.fire( 'saveSnapshot' );
        console.log( widget.data.url ); // The above URL. It is only changed
                                        // once the content is successfully loaded.
    },

    errorCallback: function( message ) {
        editor.showNotification( widget.getErrorMessage( message, url ), 'warning' );
    }
} );
```
Parameters

url : String

Resource URL to be embedded.

opts : Object

Returns

request
toFeature() → feature

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
_cacheResponse( url, response )

See source
Caches the provider response.

Parameters

url : String

response : Object
private
_createTask() → task

See source
Creates a notification aggregator task.

Returns

task
private
_getCachedResponse( url ) → Object | undefined

See source
Returns the cached response.

Parameters

url : String

Returns

Object | undefined

Response or undefined if the cache was missed.
private
_handleError( request, messageTypeOrMessage )

See source
Handles an error. An error can be caused either by a request failure or an unsupported oEmbed response type.

Parameters

request : request

messageTypeOrMessage : String

See getErrorMessage.
private
_handleResponse( request ) → Boolean

See source
Handles the response of a successful request.

Fires the handleResponse event in order to convert the oEmbed response to HTML that can be embedded.

If the response can be handled, the content is set.

Parameters

request : request

Returns

Boolean

Whether the response can be handled. Returns false if handleResponse was canceled or the default listener could not convert oEmbed response into embeddable HTML.
private
_responseToHtml( response ) → String | null

See source
Returns embeddable HTML for an oEmbed response if it is of the photo, video or rich type.

Parameters

response : Object

The oEmbed response.

Returns

String | null

HTML string to be embedded or null if this response type is not supported.
private
_sendRequest( request )

See source
Sends the request to the provider using the JSONP technique.

Parameters

request : request
private
_setContent( url, content )

See source
The very final step of content loading. The url data property is changed and the content is embedded (CKEDITOR.plugins.widget.element's HTML is set).

Parameters

url : String

The resource URL.

content : String

HTML content to be embedded.

Events

handleResponse( evt )
See source
Fired after receiving a response from the provider. This event listener job is to turn the oEmbed response to embeddable HTML by setting evt.data.html.
```
widget.on( 'handleReaponse', function( evt ) {
    evt.data.html = customOembedToHtmlConverter( evt.data.response );
} );
```
This event can also be canceled to indicate that the response cannot be handled. In such case the evt.data.errorMessage must be set (see getErrorMessage).
```
widget.on( 'handleReaponse', function( evt ) {
    if ( evt.data.response.type == 'photo' ) {
        // Will display the editor.lang.embedbase.unsupportedUrl(Given) message.
        evt.data.errorMessage = 'unsupportedUrl';
        evt.cancel();
    }
} );
```
This event has a default late-listener (with a priority of 999) that, if evt.data.html has not been set yet, will try to handle the response by using the _responseToHtml method.

Parameters

evt : eventInfo

`sendRequest( evt )`

See source

Fired by the loadContent method to dispatch a request to the provider. You can cancel this event and send the request using a different technique. By default, if the event is not stopped or canceled a request will be sent using the JSONP technique.

widget.on( 'sendRequest', function( evt ) {
    var request = evt.data;

    // Send the request using a technique of your choice (XHR with CORS for instance).
    myApp.requestOembedProvider( request.url, function( err, response ) {
        if ( err ) {
            request.errorCallback( err );
        } else {
            request.callback( response );
        }
    } );

    // Do not call other listeners, so the default behavior (JSONP request)
    // will not be executed.
    evt.stop();
} );

Parameters

evt : eventInfo

validateUrl( evt )

See source
Fired by the isUrlValid method. Cancel the event to make the URL invalid.

Parameters

evt : eventInfo

CKEDITOR.plugins.embedBase.baseDefinition

Filtering

Properties

allowedContent : allowedContentRulesCKEDITOR.plugins.embedBase.baseDefinition#allowedContent

button : StringCKEDITOR.plugins.embedBase.baseDefinition#button

contentForms : ObjectCKEDITOR.plugins.embedBase.baseDefinition#contentForms

contentTransformations : ObjectCKEDITOR.plugins.embedBase.baseDefinition#contentTransformations

data : FunctionCKEDITOR.plugins.embedBase.baseDefinition#data

defaults : ObjectCKEDITOR.plugins.embedBase.baseDefinition#defaults

dialog : StringCKEDITOR.plugins.embedBase.baseDefinition#dialog

downcast : String | FunctionCKEDITOR.plugins.embedBase.baseDefinition#downcast

downcasts : ObjectCKEDITOR.plugins.embedBase.baseDefinition#downcasts

draggable : BooleanCKEDITOR.plugins.embedBase.baseDefinition#draggable

edit : FunctionCKEDITOR.plugins.embedBase.baseDefinition#edit

editables : ObjectCKEDITOR.plugins.embedBase.baseDefinition#editables

getLabel : FunctionCKEDITOR.plugins.embedBase.baseDefinition#getLabel

init : FunctionCKEDITOR.plugins.embedBase.baseDefinition#init

inline : BooleanCKEDITOR.plugins.embedBase.baseDefinition#inline

insert : FunctionCKEDITOR.plugins.embedBase.baseDefinition#insert

Parameters

mask : Boolean | StringCKEDITOR.plugins.embedBase.baseDefinition#mask

inherited name : StringCKEDITOR.plugins.embedBase.baseDefinition#name

parts : ObjectCKEDITOR.plugins.embedBase.baseDefinition#parts

pathName : StringCKEDITOR.plugins.embedBase.baseDefinition#pathName

providerUrl : templateCKEDITOR.plugins.embedBase.baseDefinition#providerUrl

requiredContent : contentRuleCKEDITOR.plugins.embedBase.baseDefinition#requiredContent

since 4.4.0 styleToAllowedContentRules : FunctionCKEDITOR.plugins.embedBase.baseDefinition#styleToAllowedContentRules

Parameters

since 4.4.0 styleableElements : StringCKEDITOR.plugins.embedBase.baseDefinition#styleableElements

template : StringCKEDITOR.plugins.embedBase.baseDefinition#template

upcast : String | FunctionCKEDITOR.plugins.embedBase.baseDefinition#upcast

since 4.5.0 upcastPriority : NumberCKEDITOR.plugins.embedBase.baseDefinition#upcastPriority

upcasts : ObjectCKEDITOR.plugins.embedBase.baseDefinition#upcasts

urlRegExp : RegExpCKEDITOR.plugins.embedBase.baseDefinition#urlRegExp

private _cache : ObjectCKEDITOR.plugins.embedBase.baseDefinition#_cache

Methods

since 4.13.0 getClipboardHtml() → StringCKEDITOR.plugins.embedBase.baseDefinition#getClipboardHtml

Returns

getErrorMessage( messageTypeOrMessage, [ url ], [ suffix ] ) → StringCKEDITOR.plugins.embedBase.baseDefinition#getErrorMessage

Parameters

Returns

isUrlValid( url ) → BooleanCKEDITOR.plugins.embedBase.baseDefinition#isUrlValid

Parameters

Returns

loadContent( url, opts ) → requestCKEDITOR.plugins.embedBase.baseDefinition#loadContent

Parameters

Returns

toFeature() → featureCKEDITOR.plugins.embedBase.baseDefinition#toFeature

Returns

private _cacheResponse( url, response )CKEDITOR.plugins.embedBase.baseDefinition#_cacheResponse

Parameters

private _createTask() → taskCKEDITOR.plugins.embedBase.baseDefinition#_createTask

Returns

private _getCachedResponse( url ) → Object | undefinedCKEDITOR.plugins.embedBase.baseDefinition#_getCachedResponse

Parameters

Returns

private _handleError( request, messageTypeOrMessage )CKEDITOR.plugins.embedBase.baseDefinition#_handleError

Parameters

private _handleResponse( request ) → BooleanCKEDITOR.plugins.embedBase.baseDefinition#_handleResponse

Parameters

Returns

private _responseToHtml( response ) → String | nullCKEDITOR.plugins.embedBase.baseDefinition#_responseToHtml

Parameters

Returns

private _sendRequest( request )CKEDITOR.plugins.embedBase.baseDefinition#_sendRequest

Parameters

private _setContent( url, content )CKEDITOR.plugins.embedBase.baseDefinition#_setContent

Parameters

Events

handleResponse( evt )CKEDITOR.plugins.embedBase.baseDefinition#handleResponse

Parameters

sendRequest( evt )CKEDITOR.plugins.embedBase.baseDefinition#sendRequest

Parameters

validateUrl( evt )CKEDITOR.plugins.embedBase.baseDefinition#validateUrl

Parameters

`allowedContent : allowedContentRules`

`button : String`

`contentForms : Object`

`contentTransformations : Object`

`data : Function`

`defaults : Object`

`dialog : String`

`downcast : String | Function`

`downcasts : Object`

`draggable : Boolean`

`edit : Function`

`editables : Object`

`getLabel : Function`

`init : Function`

`inline : Boolean`

`insert : Function`

`mask : Boolean | String`

inherited
`name : String`

`parts : Object`

`pathName : String`

`providerUrl : template`

`requiredContent : contentRule`

since 4.4.0
`styleToAllowedContentRules : Function`

since 4.4.0
`styleableElements : String`

`template : String`

`upcast : String | Function`

since 4.5.0
`upcastPriority : Number`

`upcasts : Object`

`urlRegExp : RegExp`

private
`_cache : Object`

since 4.13.0
`getClipboardHtml() → String`

`getErrorMessage( messageTypeOrMessage, [ url ], [ suffix ] ) → String`

`isUrlValid( url ) → Boolean`

`loadContent( url, opts ) → request`

`toFeature() → feature`

private
`_cacheResponse( url, response )`

private
`_createTask() → task`

private
`_getCachedResponse( url ) → Object | undefined`

private
`_handleError( request, messageTypeOrMessage )`

private
`_handleResponse( request ) → Boolean`

private
`_responseToHtml( response ) → String | null`

private
`_sendRequest( request )`

private
`_setContent( url, content )`

`handleResponse( evt )`

`sendRequest( evt )`

`validateUrl( evt )`