CKEditor Html Helpers for ASP.NET MVC Razor/WebForms Views

by Andrew Barber 16. April 2011 10:27

This post describes a set of HTML Helpers I've written for use in an ASP.NET MVC 3 web site project, which enable you to insert a CKEditor instance with no more effort than this:

@Html.CKEditorHeaderScripts()
...
@Html.CKEditorFor(model => model.Body)
...
<input type="submit" value="Save"
 onclick="@Html.CKEditorSubmitButtonUpdateFunction()" />

This solution requires jQuery, CKEditor3, and the jQuery adapter which comes with CKEditor. It enables client-side validation to work with the editor via the helper used in the onclick handler of the submit button. It works with both Razor and WebForms view engines, and includes all of the strong-typed Html Helpers you would expect, and almost all of the weak typed ones as well. Read on to see how to use it, and download it for use in your projects.

Usage of CKEditor HTML Helpers for MVC

Once you have included the single source file, enabled jQuery for the project, and have the standard client-side code that is injected into MVC3 editor views, you simply use the following helper once per view to enable the plumbing needed. I put it right after the two validation-related jQuery scripts:

<script src="/Scripts/jquery.validate.min.js" type="text/javascript"></script>
<script src="/Scripts/jquery.validate.unobtrusive.min.js" type="text/javascript"></script>
@Html.CKEditorHeaderScripts()

That helper simply outputs the CKEditor scripts required, and defines a javascript function which calls updateElement() on all CKEditor instances before client-side validation is done. Then, you use the various overloads of CKEditor()/CKEditorFor() to output your actual CKEditor instances. These helpers are based directly on MVC3's TextArea()/TextAreaFor() helpers, and will output essentially the same HTML as those helpers, meaning non-Javascript browsers will simply see normal textareas. Once the helper has rendered the textarea output, it then adds a jQuery call to initialize a CKEditor instance, add a special CSS class, and allows you to define your own CKEditor config/callback information.

Following are some helper calls you could do with this:

@Html.CKEditor("Body", (string)ViewBag.BodyText, "toolbar:'Basic'"new{cols=20, rows=5})
@Html.CKEditorFor(model => model.Body, rows: 5, columns: 40);
@Html.CKEditorFor(model => model.Body, "uiColor:'#996611'")
@Html.CKEditorFor(model => model.Body)

The pattern of the overloads defined is very similar to those for TextArea/TextAreaFor, with the addition of the string parameter ckEditorConfig. In the case of the weak-typed CKEditor() methods, you must define the value parameter for all overloads. Beyond that, all of the overloads you would expect will exist.

Finally, to enable client-side validation upon submission of the form which contains one or more CKEditor instances, a helper method is defined which calls a Javascript function that was injected previously. That function uses the CSS class added as a jQuery selector to call the CKEditor updateElement() method on each one. Without doing this, a CKEditor for a model field with the data annotations 'Required' attribute would falsely be indicated as being empty the first time you click to submit the form.

<input type="submit" value="Save"
 onclick="@Html.CKEditorSubmitButtonUpdateFunction()" />

Caveats for Usage

The non-typed CKEditor() helpers all require you to specify a value, except for the most simplified one. You may simply provide the empty string if you like. This was due to the complexities that would have ensued from trying to provide extra overloads with the ckEditorConfig parameters I was adding.

If you provide a ckEditorConfig value, you should do so in javascript config syntax, as a literal string (eg @Html.CKEditorFor(model=>model.Data, "{toolbar: 'Basic', uiColor: 'Red'}")). The helpers will provide the surrounding squiggly brackets if you forget them. Doing so will override the height and width config values that the helpers normally set themselves. You can use a custom config file, or the CKEditor standard config file to set default values, including sizes, to make using instance-specific config information simpler.

CKEditor HTML Helpers Installation and Configuration

First, download this zip. It contains a single .cs file, which is the full source code for the helpers:

CKEditorHelpers.zip

Unzip the CKEditorHelpers.cs file and add it to your MVC project wherever seems appropriate. Then open the file, and investigate the few items at the top which may need alteration:

/* The following values should be configured to your application/desires. */
/// The CSS Class for CKEditor instances, for internal use by these helpers
private const string CK_Ed_Class = "ckEditorBoxGen";
/// The virtual, rooted directory where CKEditor can be found.
/// Should include trailing slash. eg /CKEditor/
private const string CK_Ed_Location = "/CKEditor/";
/// The default rows of textarea/em height of CKEditor
private const int DefaultTextAreaRows = 20;
/// The default columns of textarea/em width of CKEditor
private const int DefaultTextAreaColumns = 40;

These should all be pretty self-explanatory. The CK_Ed_Class need not be altered unless you think it will conflict with a CSS class you have elsewhere. The default text area sizes will be set as style properties on the textarea tag in em units, and sent to the CKEditor instance as height and width in em units. Note that the textarea size on browsers without Javascript likely will not be exactly the same as the CKEditor box would be, but they will be close. You can override these textarea values in the helper's overloads, and you can also set CKEditor config values with the proper overloads. You could do both if you wish to fine-tune the sizes so that they match exactly with or without the javascript editor.

You needn't read on if you merely wish to use the helpers; that should cover everything you need. Feel free to leave comments here or use the 'Contact' page on this site if you have questions, comments or recommendations.

Examining the Source Code of the CKEditor HTML Helpers

I started developing these helpers from the source code of ASP.NET MVC3 RTM's TextAreaExtensions.cs file. Therefore, most of the internal conventions for Html helpers will have been applied for the CKEditor helpers, too. The bulk of the code is the various overloads of CKEditor()/CKEditorFor(); I have surrounded those with regions to make it easier to explore the code. In the "Related HTML Helpers" region are the two other helpers; the one that sets up the 'header' scripts (which do not necessarily need to be in the HTML head) and the one that outputs the call to trigger the update function. Both merely output short bits of javascript.

public static MvcHtmlString CKEditorHeaderScripts(this HtmlHelper help) {
return MvcHtmlString.Create(@"
<script src=""" + CK_Ed_Location + @"ckeditor.js"" type=""text/javascript""></script>
<script src=""" + CK_Ed_Location + @"adapters/jquery.js"" type=""text/javascript""></script>
<script type=""text/javascript"">
 function UpdateCKEditors() {
$('." + CK_Ed_Class + @"').ckeditorGet().updateElement(); }
</script>
");
}

As you can see, it is using some of the constants defined at the top to include the CKEditor script and jQuery adapter. Alter these if you need to. It also defines a function which will be used to call the updateElement() CKEditor function on all of the CKEditor instances created by the helpers. This function updates the underlying DOM with the data for the textarea so that validators which run before the POST happens will see the correct information. So, then we have this:

public static MvcHtmlString CKEditorSubmitButtonUpdateFunction(this HtmlHelper help) {
return MvcHtmlString.Create("javascript:UpdateCKEditors()");
}

This is merely a convenience for the sake of Intellisense support, to be added to the onclick event of the form's submit button, or in another appropriate location to be called before the validators would fire. You could of course simply call the UpdateCKEditors() javascript function in any other way you would like.

The meat-and-drink of the main array of helpers is a private method to which they all eventually delegate, CKEditorHelper(). This method builds the underlying textarea tag in almost exactly the same way as the MVC3 built-in TextAreaHelpers.cs source code does. The difference is that it uses styles to define the size of the textarea rather than the cols and rows attributes, to better match the sizes of the textarea to the javascript-enabled CKEditor.

Of key importance to note here is that since I use the same code that Microsoft did to build the textarea, it should work exactly as you would expect any other helper form control. For example, if you use prefixes for field names. After the textarea is built up, the script tag which enables the CKEditor is then also created:

TagBuilder scriptBuilder = new TagBuilder("script");
scriptBuilder.MergeAttribute("type""text/javascript");
if (string.IsNullOrEmpty(ckEditorConfigOptions)) {
ckEditorConfigOptions =
string
.Format("{{ width:'{0}em', height:'{1}em' }}",
 rowsAndColumns["cols"], rowsAndColumns["rows"]
);
}
if (!ckEditorConfigOptions.Trim().StartsWith("{"))
 ckEditorConfigOptions = "{" + ckEditorConfigOptions;
if (!ckEditorConfigOptions.Trim().EndsWith("}"))
 ckEditorConfigOptions += "}";
scriptBuilder.InnerHtml = string.Format(" $('#{0}').ckeditor({1}).addClass('{2}'); ",
fullName,
ckEditorConfigOptions,
CK_Ed_Class
);

You can see where I set the CKEditor config options for the width and height based on the 'rols' and 'rows' info, unless you have provided your own configuration information. This code could be improved to parse the supplied config info, and add in the width and height items each only if that item was not already supplied. Finally, the curly braces are added if they weren't supplied already, then the jQuery call which creates the CKEditor and adds the custom CSS class is written. The textarea and script elements are concatenated and output, and that's it!

Conclusion and What's Coming

Hopefully, this is helpful to someone. As simple as CKEditor is to integrate into a web site, this makes it that much easier with ASP.NET MVC3. Please feel free to comment or contact me if you have any questions, comments or ideas for improvement.

If you missed it above, here is the source download link: CKEditorHelpers.zip

Coming up, I will post my solution to use the old file browser/uploader from FCKEdit with CKEditor, and how I integrated that with ASP.NET MVC, as well.

Comments


April 20. 2011 14:45
What he said. (He asked for a comment. I just wanted to be of assistance. I could pimp my web site http://robinsdesktop.com and annoy everyone. But, I won't.)


April 20. 2011 15:36
You're more than welcome to pimp your website, Robin, seeing as how I certainly endorse your virtual assistant services!


April 29. 2011 02:47
This is nice post which share better idea about CKEditor Helps to HTML. CKEditor is to accommodate into a web site, this makes it that abundant easier with ASP.NET MVC3. really this is interesting and beneficial information here.


April 29. 2011 11:46
Nice post, I was looking for a solution to the Required attribute not working in MVC3 with CKEditor. What I took out from your code is that part :

$('.text-editor').ckeditor();
$('input[type=submit]').bind('click', function() {
    $('.text-editor').ckeditorGet().updateElement();
});

I simply bind it on the css class but I like your helper, it's a good idea but a bit overkill.


May 5. 2011 17:59
@Vincent - it doesn't save a lot of keystrokes each individual time it is used, certainly. However, it mostly saves 'brain time' each time I need to add a CKEditor instance somewhere. Provided jQuery is already on the page, it's three, quick Intellisense-aware snippets and I'm done.

The 'brain time' comment is because in practice, I have to remember the various things to get the editor to work. Line-of-code wise, it's about the same; but there's nothing really to remember, now. Just Html.CK... and Intellisense handles the rest.


May 6. 2011 01:54
i hate ckeditor, even if it makes some tasks easier i find it very complicated


May 6. 2011 11:28
@mapquest - From the end-user's standpoint, I always simplify the buttons on the menus; The Basic template is way too sparse, but the Full one has far too many confusing options for its typical use formatting simple HTML content.

From the developer standpoint, it's not much more complex than any other editor out there to implement. For my clients, a WYSIWYG editor is an absolute must (and to be honest - I prefer to use it for most things, provided I have that "Source" button available)


 dheerendra 
May 17. 2011 05:50
Hi

i am uisng u r ckeditor in mvc 3 application,i want a complete editor but this one is not showing b,u i,and many other tag,it just showing simple textbox.


plesae help me out its urgent



 Ignatius 
May 24. 2011 02:57
Thanks so much. This helps a lot as I've never used CKEditor before and I've only recently started on ASP.NET MVC.


 Juan Pablo Pérez 
May 26. 2011 02:52
Andrew,

This is a good job. Thank you very much. There is a small bug in the code in line 360:
scriptBuilder.InnerHtml = string.Format(" $('#{0}').ckeditor({1}).addClass('{2}'); ",
        textAreaBuilder.Attributes["id"], //fullName
        ckEditorConfigOptions,
        CK_Ed_Class
        );

Juan Pablo


 mark 
June 13. 2011 09:36
Hi,
Learning mvc and I needed to implement a ckeditor.
Do you happen to have a solution to download?

Also I need to save the content to table in sql server how do you hook into the savemethod?
Sorry for very beginner question but new to the web world.
thanks a lot


June 14. 2011 15:07
@Juan Thanks for that; I will check that out and correct that, if need be.

Comments are closed
Disclaimer
The opinions expressed herein are my own personal opinions and do not represent those of my partners, clients or contractors in any way.

© Copyright 2014 AndrewBarber.com