CKEditor version 3 (previous called FCK Editor, but had its name change due to political posturing) was release in Aug 2009, and they have yet to release an ASP.NET control to make it easier to use in an ASP.NET environment. We wanted to upgrade the Syrinx Community Server's (SCS) usage of the editor to the latest, so we wrote our own and made it open source so anyone can use it.
The CKEditor product is a great jump up in functionality over the previous version. They have revamped everything and its more consistent in how plug-ins work. I noticed it was much faster to load in our products than the prior version, and we were able to port our SCS specific plug-ins over in just a few hours, even though there is a lack of documentation on what to do. In order to understand the process, I wrote some notes on how things work in the new plug-in environment and have made a user guide from that.
One really nice improvement in how the new editor works is that configuration is passed in on the creation of the editor in the browser. Overall, the new editor is much more flexible with the way it is configured and offers a nice cascading option that allows for configuration to be provided inline with the editor, as a separate js file, or built into the core products js. We made it easy to use these various ways of configuration within the ASP.NET control.
Getting the Control To Work
1. We do not distribute the CKEditor base javascript, so you'll need to download that as well. Our demo ASP.NET that is a part of our distribution does include a version of CKEditor, but the ASP.NET library itself does not, and you should download the latest from http://ckeditor.com. The ASP.NET code will automatically add the JS include on the page it is in, but it does expect the code to be in a directory called ckeditor by default. You can change that by setting the static CkEditorJS property on the ASP.NET control, which also will allow you to change the name of the ckeditor.js file if you've customized it in some way. It is recommended that you put the CKEditor javascript distribution in the standard directory of ckeditor and not change the CkEditorJS property.
2. Add the reference to the SyrinxCkEditor.dll to your ASP.NET site.
3. Add a reference to the control assembly to your ASP.NET page.
4. Use the control. The simplest server side definition of the control is:
About the ASP.NET Control
The ASP.NET control is completely compatible with the ASP.NET theme structure, and is skinable. All of the major properties of the control are setup to be configured in ASP.NET skin files, which makes it much easier to do things like have different skins for editors that need different levels of toolbar support. In previous version of FCKEditor the standard was to define custom toolbars in the config file within the distribution. This made it more difficult to upgrade the editor to a newer version. Now, toolbar configurations can be defined in a theme skin, or in an external JS file.
ASP.NET ViewState is support for all properties except the Text property. This allows the controls configuration to be changed in event handlers and be remembered properly as standard ASP.NET events take place. Because very large documents can be edited in the control, it was decided to not use ViewState for the Text property to avoid the ViewState becoming too large. However, the ASP.NET control does implement the ASP.NET IPostBackDataHandler interface and uses that to get the value of the editor from the form post data and place it back in the Text property. The only loss from not using ViewState for the Text property is that the control cannot tell that the editor contents have changed during a postback and thus it does not raise a text changed event.
Our CkEditor control also inherits from ITextControl, make it plug and play with the standard ASP.NET text controls like the TextBox. This made integration into our SCS product easier, as we already had good support for the ITextControl interface.
One goal we had with the ASP.NET control is to make it really easy to inherit from the class to provide specific server side behavior beyond what comes with the base class provided here. The process of building up the configuration options and the html for the browser are all marked virtual, and were designed with inheritance in mind. In our SCS product, we have another class that inherits from this to integrate within our environment better, such as automatically switching the language used by the editor based on the user's selected culture. We also use it to resolve macros embedded in configuration options based on SCS's macro environment.
Because we are using this ASP.NET control in our production systems, we know it is solid and works well. There do seem to be some minor bugs in the way the new CKEditor works, but overall we are very happy with the move and highly recommend that if you are using an older version of FCKEditor, to make the jump up. We hope this ASP.NET control will make the job easier for you.
ASP.NET Control Details
The CkEditor exposes a great number of configuration options in its CKEDITOR.config class. Things like what language to use, if the toolbar is collapsed, and can the editor be resized are all set in that javascript class. The ASP.NET control provides many properties to properly setup those configuration options.
The CKEditor javascript gets an editor started by calling its replace method, passing in some HTML object to put the editor in. The standard HTML object to use is the TextArea. The TextArea works well because it also serves as a form element that can have its content submitted in a form post back. In fact, the editor is designed to maintain its content within its given TextArea so when the form is posted back, whatever has been edited within it will go up to the server properly.
Along with the HTML object, the replace method can also be given a javscript object that defines configuration values that match up to those defined in the CKEDITOR.config class. A powerful aspect of this class is that new plug-ins can expose configuration options through it as well, so the options specified in the CKEDITOR.config from a standard install can be expanded on by adding additional plug-ins. Many of the standard plug-ins add their own configuration options like this.
The ASP.NET control exposes many of the configuration options as real properties on the class itself. For example, the CKEDITOR.config.removePlugins option is exposed via the ASP.NET control's RemovePlugins property. Because not all the standard properties are currently exposes via class properties, and countless new plug-ins could add more configuration, the ASP.NET control offers an ExtraConfig property that allows any javascript object type properties to be defined in it. The follow shows the CKEDITOR.config.format_h6 property being set via the ASP.NET controls ExtraConfig property:
ExtraConfig="format_h6: {element:'h6', attributes:{'class':'contenth6'}}"
The ExtraConfig property can accept a comma delimited list of name:value pairs like that shown above.
The vast majority of these configuration properties are set with the Attribute Category set to Appearance so that when the control is configured in the ASP.NET skin file, the configuration can be specified in the skin. I use this to defined several variations of configuration for "full edit", "basic Edit", etc.. Each of these skinned editors uses different toolbar definitions, plugins and more. During the ASP.NET page's PreInit event, you can set the skin of the editor based on the logged in user so that users with higher security privileges would use a different configuration for the editor.
However, using skin files like that isnt exactly what Microsoft had in mind. Microsoft specifically states to only use set the Category attribute to appearance on properties that drive appearance and should only be used in the context of variations from one theme to another. My usage of it breaks that a bit, but it works well.
The CKEDITOR.config.customConfig property is designed to be used in similar ways. Rather than using skins, you could set the ASP.NET controls ExternalConfigJs property to a js file in the site that defines all the properties you want and set it in a similar way as I've outlined for using ASP.NET skins. The js file specified in the ExternalConfigJs would define a javascript object with the configuration options set as name:value pairs.
The ASP.NET control Output
The Render override in the ASP.NET control generates the core html and javascript calls needed to get the editor to start properly. The method is written to always use the textarea HTML element for the editor so that it can count on the edited text being sent back to it during an ASP.NET post back process. When the Text property of the control is set, the contents of the text are not put within the inside of the textarea. The text is actually embedded into a generated JS string, which is given to the editor after it is created. From various trial and error situations, using a javascript string variable to hold the contents and then calling the CKEditor.setData method is the most reliable approach to content. I've run into some odd scenarios where textareas contained within textareas contained within textareas (what a mouthfull) can cause the editor to not properly display the value. This is true even when using text like "</textarea>" over "</textarea>" for the content being placed within the main textarea. It is also less work on the server to prep the html content for the editor for a javascript string rather than real html embedded in the main editor textarea.
Control Javascript Setup
The ASP.NET control will add the javascript link for the main ckeditor.js file on its own, so you should not add the script block for that file, just add the ASP.NET control to the pages you want to use it in and make sure the ckeditor directory with all the javascript and other support files is in the root of your site.
The control will also generate its own javascript block for each editor on the page that will call the CKEDITOR.replace method to turn the textarea into the actual rich HTML editor. One interesting thing this code does is check to see if there is an editor instance already created with the same id as the one being created and if so, it will call the CKEDITOR.remove method on that one first. This is particularly important in a heavy ajax environment. For example, in the Syrinx Community Server, an authorized user can toggle between a standard view on content and the editor view of the content for an article with a simple ajax button click. That process will create and destroy the CkEditor each time the user cycles through the edit. Calling remove if the editor was previous defined helps to ensure there is no javascript error from trying to define another editor instance with the same id as a previous one.
When the config options to be passed are needed in the render process, it calls the buildConfigOptions method, which is defined as virtual. This method will call the innerBuildConfigOptions method which will generate a comma delimited list of name:value pairs without the outer { } around them. If there are name:value pairs returned from calling the innerBuildConfigOptions method, the buildConfigOptions method will wrap it with the { }, otherwise it will return an empty string so that the replace method is called without the extra config options parameter. The innerBuildConfigOptions method is also defined as virtual.
You can easily build another class that inherits from the CkEditor ASP.NET control so that you can augment the process of rendering the overall html or javascript to be sent to the browser. In The Syrinx Community Server, we override the innerBuildConfigOptions to more tightly integration with the SCS environment such as automatically setting the language property based on the users language for the site and the replace embedded SCS macros within configuration options.