Revision as of 16:57, 4 March 2011

CKEditor is a highly customizable tool and the full list of all configuration options is available in the JavaScript API. The config configuration object of CKEditor.NET contains all configuration options of the standard CKEditor release, as available in the JavaScript API documentation.

The CKEditor.NET Control also contains some of the frequently used and thus most useful configuration options in a form of CKEditor control properties. These properties can be set both in the source code and in Visual Studio visual designer, where they can be seen in the Properties window.

CKEditor.NET Control Properties

The names of the CKEditor.NET properties use the ASP.NET naming conventions and are written in Pascal case. Check some of the comparisons between the JavaScript names and ASP.NET ones.

Orginal JavaScript name:

CKEditor1.config.format_tags = "p;h1;h2;h3;h4;h5;h6;pre;address;div";
CKEditor1.config.defaultLanguage = "en";

ASP.NET name in Pascal case:

CKEditor1.FormatTags = "p;h1;h2;h3;h4;h5;h6;pre;address;div";
CKEditor1.DefaultLanguage = "en";

Passing Configuration String Values

Please note that CKEditor.NET settings that are represented by string objects when passed from ASP.NET to JavaScript do not require additional quote characters as they will be converted to the JSON format automatically.

CKEditor1.config.defaultLanguage = "en";
CKEditor1.config.filebrowserImageBrowseUrl = "~/ckfinder/ckfinder.html?type=Images";
CKEditor1.config.filebrowserImageUploadUrl = "~/ckfinder/core/connector/aspx/connector.aspx?command=QuickUpload&type=Images";
CKEditor1.config.format_div = @"{ element : 'div' }";
CKEditor1.config.toolbar = "Full";
CKEditor1.config.toolbar = new object[] { new object[] { "Source", "About" } };

Methods of Setting Configuration

The configuration of the CKEditor.NET Control can be set in two different ways.

Firstly, you can define the configuration in the source file, inside the <script> element (either inline or in the external source file).

<script language="C#" runat="server">
    protected void Page_Load(object sender, EventArgs e)
    {
	CKEditor1.config.toolbar = "Basic";
    }
</script>

Secondly, you can set the same property in the CKEditor.NET control tag on the .aspx page.

<CKEditor:CKEditorControl ID="CKEditor1" runat="server" Toolbar="Basic">
</CKEditor:CKEditorControl>

Do remember, though, that if you use both methods at the same time, the definition from the source code will prevail and override the one from the CKEditor.NET control tag.

Toolbar Definition

CKEditor toolbar can be defined in a similar way as in JavaScript, using an array of objects representing toolbar elements (buttons, drop-down menus).

The toolbar can be defined inside the source code file.

CKEditor1.config.toolbar = new object[]
{
	new object[] { "Source" },
	new object[] { "Bold", "Italic", "Underline", "Strike", "-", "Subscript", "Superscript" },
	new object[] { "NumberedList", "BulletedList", "-", "Outdent", "Indent" },
	"/",
	new object[] { "Styles", "Format", "Font", "FontSize", "TextColor", "BGColor", "-", "About" },
};

It can also be defined inside the .aspx page.

<CKEditor:CKEditorControl ID="CKEditor1" runat="server" 
Toolbar="Source
Bold|Italic|Underline|Strike|-|Subscript|Superscript
NumberedList|BulletedList|-|Outdent|Indent
/
Styles|Format|Font|FontSize|TextColor|BGColor|-|About">
</CKEditor:CKEditorControl>

CKEditor comes with two predefined toolbar sets, so instead of providing the full definition of a toolbar it is possible also to specify simply the name of a toolbar:

CKEditor1.config.toolbar = "Full";

<CKEditor:CKEditorControl ID="CKEditor1" runat="server" Toolbar="Full">
</CKEditor:CKEditorControl>

Options Defined as Enumerators

Some configuration options that let you select one or more pre-defined options are implemented as enumerators. You can set them in the following way.

Inside the source code file:

CKEditor1.config.contentsLangDirection = contentsLangDirections.Ui;
CKEditor1.config.dialog_buttonsOrder = DialogButtonsOrder.OS;
CKEditor1.config.enterMode = EnterMode.P;
CKEditor1.config.resize_dir = ResizeDir.Both;
CKEditor1.config.scayt_contextCommands = ScaytContextCommands.All;
CKEditor1.config.scayt_contextMenuItemsOrder = ScaytContextMenuItemsOrder.Suggest | ScaytContextMenuItemsOrder.Moresuggest;
CKEditor1.config.scayt_moreSuggestions = ScaytMoreSuggestions.On;
CKEditor1.config.shiftEnterMode = EnterMode.P;
CKEditor1.config.startupMode = StartupMode.Wysiwyg;
CKEditor1.config.toolbarLocation = ToolbarLocation.Top;

Inside the .aspx page:

<CKEditor:CKEditorControl ID="CKEditor1" runat="server" Toolbar="Full" ContentsLangDirection="Ui" DialogButtonsOrder="OS" 
	EnterMode="P" ResizeDir="Both" ShiftEnterMode="P" StartupMode="Wysiwyg" ToolbarLocation="Top">
</CKEditor:CKEditorControl>

Options Defined as Arrays

Some CKEditor options (like smiley_images or specialChars) are defined in JavaScript as array objects, in the following way:

config.smiley_descriptions =
    [
        'smiley', 'sad', 'wink', 'laugh', 'frown', 'cheeky', 'blush', 'surprise',
        'indecision', 'angry', 'angel', 'cool', 'devil', 'crying', 'enlightened', 'no',
        'yes', 'heart', 'broken heart', 'kiss', 'mail'
    ];

To define them using ASP.NET, use the following form:

CKEditor1.config.smiley_descriptions = new string[]
{
	"smiley", "sad", "wink", "laugh", "frown", "cheeky", "blush", "surprise",
	"indecision", "angry", "angel", "cool", "devil", "crying", "enlightened", "no",
	"yes", "heart", "broken heart", "kiss", "mail"
};

CKEditor1.config.blockedKeystrokes = new int[]
{
	CKEditorConfig.CKEDITOR_CTRL + 66 /*B*/, CKEditorConfig.CKEDITOR_CTRL + 73 /*I*/, CKEditorConfig.CKEDITOR_CTRL + 85 /*U*/
};

CKEditor1.config.keystrokes = new object[] 
{ 
	new object[] { CKEditorConfig.CKEDITOR_ALT + 121 /*F10*/, "toolbarFocus" },
	new object[] { CKEditorConfig.CKEDITOR_ALT + 122 /*F11*/, "elementsPathFocus" },
	new object[] { CKEditorConfig.CKEDITOR_SHIFT + 121 /*F10*/, "contextMenu" },
	new object[] { CKEditorConfig.CKEDITOR_CTRL + 90 /*Z*/, "undo" },
	new object[] { CKEditorConfig.CKEDITOR_CTRL + 89 /*Y*/, "redo" },
	new object[] { CKEditorConfig.CKEDITOR_CTRL + CKEditorConfig.CKEDITOR_SHIFT + 90 /*Z*/, "redo" },
	new object[] { CKEditorConfig.CKEDITOR_CTRL + 76 /*L*/, "link" },
	new object[] { CKEditorConfig.CKEDITOR_CTRL + 66 /*B*/, "bold" },
	new object[] { CKEditorConfig.CKEDITOR_CTRL + 73 /*I*/, "italic" },
	new object[] { CKEditorConfig.CKEDITOR_CTRL + 85 /*U*/, "underline" },
	new object[] { CKEditorConfig.CKEDITOR_ALT + 109 /*-*/, "toolbarCollapse" }
};

Event Support

CKEditor.NET events can be added to both the global editor object and an editor instance.

To attach an event handler to an editor instance configure the CKEditorInstanceEventHandler property.

// Equivalent to CKEditor1.on in JavaScript
CKEditor1.config.CKEditorInstanceEventHandler = new System.Collections.Generic.List<object>();
CKEditor1.config.CKEditorInstanceEventHandler.Add(new object[] { "instanceReady"
	, "function (evt) { alert('Event handler attached to editor instance: ' + evt.editor.name);}" });

To attach events globally to the CKEditor object, use the CKEditorEventHandler.Add function.

// Equivalent to CKEDITOR.on in JavaScript
CKEditor1.config.CKEditorEventHandler.Add(new object[] { "instanceReady"
	, "function (evt) { alert('Events handler attached to CKEDITOR object.');}" });

Additional Configuration Options

If you want to add the configuration properties that do not come directly from CKEditor, but are available in the plugins included in your installation, use the ExtraOptions hash table.

CKEditor1.config.ExtraOptions["myConfigurationOption"] = "'sample value'";