CKEditor

From Visual WebGui Wiki
Jump to: navigation, search
VWG 64+ The content of this article is valid for version 6.4 and later, including v7.x;
Code sample projects are written in Visual Studio 2012 for v7.x, unless otherwise noted

Contents

Overview

This article demonstrates wrapping of CKEditor, the successor of FCKEditor, as a Visual WebGui control. As the makers of FCKEditor have now announced that it has become a retired product, it will not be updated and as the time passes, will lack new browser and new browser features support. CKEditor is their current product, and with this Visual WebGui wrapping, may be a worthy candidate to replace FCKEditor in your applications.

This sample requires version 6.4.0 Release or later.

Wrapping approach

The wrapping of the control takes a very similar approach as CKEditor's own ASP.NET control does. This means that almost all of the configuration settings are included as properties on the CKEditor Visual WebGui control. There are just a few exceptions where some of the properties implemented on the CKEditor's ASP.NET control are not implemented on the Visual WebGUI control, where implementing them would interfere with the Visual WebGui control, due to the wrapping.

Visual WebGui wise, the CKEditor control inherits from HtmlBox with an overridden Source property, that returns a reference to the control's Html resource. This means the control has no XSLT resource, as it's whole code is contained within that Html resouce. The reason for this approach was to allow a customized location of the CKEditor's (JavaScript) resources and this was the most efficient way for loading the resource from a custom location. Using an XSLT (or jQT) would mean more dynamic and less efficient loading of the CKEditor's resources.

Error free transfer of contents increases overhead

On rare occasions, the traditional method of transfering the edited Html content back and forth between the client and the server will fail. This will happen if the edited Html content includes patterns that do not go well with Xml. In order to guarantee error free delivery, some coding of the contents is needed to encapsulate those patterns. For the CKEditor control, base64 encoding was chosen.

This guaranteed delivery does come with a price though, as base64 encoded text means increased number of bytes that need to be transfered. In most cases, this should not be a concern, but on very slow connections with huge amounts of data, this could well become a factor.

Work in progress

The wrapping project is still a work in progress. Most of the major functionality has already been imlemented, but there will very likely be some fixes and additons made in the near futures.

The wrapping is supplied for C# only, and at the time of this writing, only for VS2008 and VS2010, as quite intensive changes need to be made for the VS2005 version, due to version differences in the C# programming language.

Still, the control is considered ready for testing for those of you that are interested.

Please report problems either on the public forums, or as an email directly to the author (Pall [dot] Bjornsson [at] Gizmox [dot] com).

The CKEditor Visual WebGui control

The Visual WebGui CKEditor control implements all of the CKEditor specific properties, methods and events with names having a "CK" prefix, with the exceptions that the CKEditor.Text property is used for the editable contents, and TextChanged event is fired when the contents change.

Three CKEditor specific events are implemented.

  • TextChanged event fires whenever the CKEditor control is loaded with new data, it looses focus or it is unloaded.
  • CKGotFocus and CKLostFocus are fired when the CKEditor control itself fires it's own internal Focus and LostFocus events. These events are implemented seperate from the GotFocus and LostFocus events available on the Visual WebGui control it self, as they would otherwise interfere with the focusing mechanism of Visual WebGui.

Many of the CKEditor's JavaScript methods are implemented as methods on the Visual WebGUI control, and you will find them on the control having the "CK" prefix to their name. Examples are: CKSetEditMode, CKGetEditMode, CKInvokeInsertElement etc. For complete list, you can view the source for the wrapped control.

Configuring the Visual WebGUI CKEditor control is almost identical to configuring the CKEditor ASP.NET control here. The config object is exposed on the Visual WebGui control via the CKConfig property.

How to use the Visual WebGUI CKEditor control

To use the CKEditor control in your application, you first need to download the CKEditor's resources and place it in a folder within your application, very similar to what was needed when using it's predecessor, the FCKEditor. You can download the most recent resources on the CKeditor website here. You should download the "Fully functional, open source editor, with source code included". The zip file contains only one folder, ckeditor, which you should then place on your application's virtual folder.

The next step is to reference the CKEditor library (that contains the wrapped CKEditor control) in your application and register the control within web.config. The control registration should look like this:

<Control Type="Gizmox.WebGUI.Forms.Editors.CKEditor, 
               Gizmox.WebGUI.Forms.Editors.CKEditor, 
               Culture=neutral, PublicKeyToken=null" />

When this is done, you can build your project, and then add CKEditor to your form.

The demo application

The demo application, included in the CKEditorTest project in the download, is just that, a demo application to demonstrate the capabilities of the most common features of the control. The demo form registeres to the most often fired events of the CKEditor control (CKGotFocus and CKLostFocus), so there is a lot of traffic when using it. Although it performs reasonable well, it will most likely be updated in the future, so it will demonstrate a more realistic use, without all those events being fired.

Requirements

  • This application works only on Visual WebGui v6.4.0 Release or later versions.
  • You are adviced to download the most recent version of CKEditor resources and use instead of the ones supplied with this demo.
  • You need to reference the CKEditor library project and you need to register the CKEditor control in your application

Changes history

  • 2011 June 17. - Original version
  • 2011 June 22. - Ability to DataBind CKEditor.Text property. Proper protection added in JavaScript, as well as forcing CKEditor's blur to fire without 100 ms delay (v002)
  • 2011 Sept 17. - Added utf8 encode/decode to support browser limited support for utf8 for handling double byte chars (like Chineese) - Thanks to Jim (v003)
  • 2011 Dec 28. - Added CKInvocationDelay property to account for the huge amount of CKEditor resources and their slow load in some situations. Defaults to 0 (v004)
  • 2012 Aug 27. - Fix to ReadOnly mode, Fix for locating resources, CKEditor resources updated to 3.6.4 (v005)
  • 2012 Aug 27. - Seperate version created for .NETHTML5 as DOCTYPE is different from WinWeb (v005_NETHTML5)
  • 2013 Apr 25. - Fixed small typo in .NETHTML5 for VS2010 (VS2010 now at v006_NETHTML5)
  • 2013 Jun 26. - Sample updated to VS2012 for VWG v7.0.1 (CKEditor_CSharp_VS2012)
  • 2013 Sep 10. - Added features for AutoSave via VWG Timer and example buttons on form (CKEditor_CSharp_VS2012_V007)
  • 2013 Sep 27. - AutoSave now has an optional Force parameter. If there is no ValueChange, a new event, ForcedChange will fire (CKEditor_CSharp_VS2012_V009)
  • 2014 Mar 18. - VWG v7.1.2 version with updated CKEditor 4.3.3 resources (CKEditor_CSharp_VS2012_V010)


Source code

Source code downloads


VWG 64 The following section is valid only for version 6.4;
WinWeb and .NETHTML5 need different downloads because of DOCTYPE change
WinWeb (XSLT & jQuery front-ends) .NETHTML5 (Mobile)
WinWeb code C# VS2008 .NETHTML5 code C# VS2008
WinWeb code C# VS2010 .NETHTML5 code C# VS2010


VWG reference The following section is a reference only section;

References

Other references