Simple Custom Widget Tutorial

Well, after so many hours of scouring the web and reading the code of other plugins, plus implementing a few of the tricks shown in the Widgets tutorials in the documentation, I have finally succeeded in creating a widget that actually changes the contents of a template!

I am turning the "Youtube" plugin into a widget so it can be moved by the user, and then edited after it's been instantiated:

plugin.js -

CKEDITOR.plugins.add('youtube-widget', {
	requires: 'widget',
	icons: 'youtube-widget',
	init: function (editor) {
		CKEDITOR.dialog.add('youtube-widget', this.path + 'dialogs/youtube-widget.js');
		editor.widgets.add('youtube-widget', {

			button: 'Widget Button Tooltip',

			//The template is the raw HTML that will be spit out by the dialog
			template:
				'<div class="youtube-widget">' +
					'<h2 class="youtube-widget-title">Title</h2>' +
					'<div class="youtube-widget-player"></div>' +					
					'<div class="youtube-widget-subtitle">Subtitle</div>' +
				'</div>',

			//You need the "parts" section to tell the dialog what part of the template to update later
			parts: {
				playerDiv: 'div.youtube-widget-player'  //this is a CSS selector of the element within the template above that you want to target - for this use, it's targeting <div class="youtube-widget-player"> from the template
			},

			//Important only if you want to have parts of your widget that can be edited without using the dialog box
			editables: {
				title: {
					selector: '.youtube-widget-title', //Notice this class is the same as the "Title" class in our template
					allowedContent: 'h2 h3 strong em'
				},
				caption: {
					selector: '.youtube-widget-subtitle',  //Again, same class as "Subtitle" element
					allowedContent: 'p br ul ol li strong em' //only these are allowed inside our caption - any other tags will be stripped, and buttons that produce anything other than what is specified here will be disabled when the user's cursor is in our Widget's Caption
				}
			},

			//Editor will remove any elements not included in this list.  elements [attributes]{styles}(classes)  (! = required)

			allowedContent:
				'div(!youtube-widget,align-left,align-right,align-center){width};' +
				'div(!youtube-widget-content); h2(!youtube-widget-title);' +
				'iframe[!width,!height,!src,!frameborder,!allowfullscreen]; object param[*];',
			
			//Tells plugin which dialog to fire when you click the button in the button toolbar
			dialog: 'youtube-widget',

			//This will find any element that you specify and forcibly turn it into a widget if it matches - useful for entering widgets via source code
			upcast: function (element) {
				return element.name == 'div' && element.hasClass('youtube-widget');
			},

			//Necessary to define the "data" object, and exposes "data.<customVariable>", like data.youtubeVideo below.  'this' refers to the widget
			init: function (widget) {
				var data = { youtubeVideo : "" };

				this.setData('youtubeVideo', this.data.youtubeVideo);
			},

			//data function is fired once user submits the dialog, after the dialog elements' own "commit" functions are processed (see dialog definition in /dialogs/<name-of-widget>.js)
			data: function (widget) {
				//Remember the "parts" variable we set up?  Here is where we use it.  setHtml() function will inject any value you want.  We want to inject the value found in the textarea of the dialog:
				this.parts.playerDiv.setHtml(this.data.youtubeVideo);  //where did this.data.youtubeVideo get set?  It was set in the "commit" function of the "txtEmbed" textarea.  (see dialog definition in /dialogs/<name-of-widget>.js)
			}
		});
	}
});

Now for the dialog code, found in the /youtube-widget/dialogs/youtube-widget.js file:

//We define our custom dialog here.  This function should "return" the object that specifies the dialog.  OK/Cancel buttons are automatically added by the Widget plugin
CKEDITOR.dialog.add('youtube-widget', function (editor) {
	return {
		title: "YouTube Video",  //Title bar of the floating dialog
		minWidth: 500, //Width/Height attributes of the dialog
		minHeight: 200,
		contents: //This should be an array of objects, separated by a comma:  contents: [{ tab1 : [{ elements }], tab2 : [{ elements }], tab3 : [{ elements }] }], using object notation
			[{
				id: 'youtubeTab', //this is the id of the tab itself.  You can add more tabs
				expand: true,
				elements:
					[{
						id: 'txtEmbed', //id of the first element in the first tab
						type: 'textarea', //textarea/textbox/select, etc.
						label: "Embed", //text label visible by user
						autofocus: 'autofocus',  //optional - autofocuses this input
						//This part validates the input - this custom widget looks for empty string, and "http://something"
						validate: function () {
							if (this.isEnabled()) {
								if (!this.getValue()) {
									alert("Empty");
									return false;
								}
								else
									if (this.getValue().length === 0 || this.getValue().indexOf('//') === -1) {
										alert("No video.");
										return false;
									}
							}
						},
						//Extremely important - this sets the value of the textarea to our data.youtubeVideo that we instantiated in the "init" function in "plugin.js"
						//Basically, it sets the value of the input when the user edits the widget
						setup: function( widget ) {
							this.setValue( widget.data.youtubeVideo);
						},
						//Necessary to do *anything* with this dialog - sets the widget.data.youtubeVideo to the value in the textarea
						commit: function (widget) {
							widget.setData( 'youtubeVideo', this.getValue() );
						}
					}]
			}]
	};
});

Feel free to point out what I'm doing wrong, or if any of this code is stupid.  Ha!

Thanks to fonini for the great YouTube plugin!

(fonini - http://ckeditor.com/users/fonini)

(Youtube plugin - http://ckeditor.com/addon/youtube)

For the googlers:

CKEditor 4 - How to set widget template to data in a textbox within a custom dialog box

I created a dialog, now what?

Custom widgets and dialogs explained

Help with creating custom widgets in CKEditor 4

(Disclaimer - this is not the complete script of the YouTube plugin/widget.  I only included the parts that are necessary for reading data from an input within a custom dialog and using them within the widget that gets output to the editor.  I will try to contact fonini to see if he wants to update the plugin with this code.  I do not own, nor did I write the YouTube plugin, just trying to change it to suit our purposes.)

Quick question... when I hit the "<> source" button in the toolbar, and then click it again to go back to design view mode, my

this.parts.playerDiv

replaces itself with "undefined".  Is there a better way to prevent this other than to check !typeof this.data.youtubeVideo !== 'undefined'"?

Why would the "data()" function fire when going between the two views?   Should I be doing the following somewhere else?

this.parts.playerDiv.setHtml(this.data.youtubeVideo)

Thanks for your attention to this matter.