CKEditor

Namespace: Wisej.Web.Ext.CKEditor

Assembly: Wisej.Web.Ext.CKEditor (4.1.0.0)

Control
- Widget
  - CKEditor

CKEditor (formerly FCKeditor) is an open source WYSIWYG text editor designed to bring common word processor features directly to web pages, simplifying their content creation. from: http://ckeditor.com/

C#
VB.NET

public class CKEditor : Widget

Public Class CKEditor
    Inherits Widget

Example:

Creating an editor in code, loading HTML content and reacting to changes:

var editor = new Wisej.Web.Ext.CKEditor.CKEditor
{
    Dock = DockStyle.Fill,
    ShowFooter = false,
    Text = "<p>Hello <strong>World</strong>!</p>"
};

editor.TextChanged += (s, e) => this.buttonSave.Enabled = true;
this.Controls.Add(editor);

Constructors

CKEditor()

Initializes a new instance of CKEditor.

Properties

BaseUrl

String: Returns or sets the base url for the CKEditor installation

This value is shared by all the CKEditor controls in the application. The default is "https://cdn.ckeditor.com/4.21.0/full-all/". Use it to load a different version or build of CKEditor, or a copy hosted with the application. The URL must end with "/" since "ckeditor.js" is appended to it. Set it once at startup, before any CKEditor control is created.

Example:

Using a copy of CKEditor deployed with the application in the /ckeditor folder:

static void Main()
{
    Wisej.Web.Ext.CKEditor.CKEditor.BaseUrl = "/ckeditor/";

    Application.MainPage = new MainPage();
}

DefaultFontNames

String[]: Returns the default font names to display in the toolbar: Verdana, Arial, Georgia and Trebuchet MS.

The returned array is shared by all the CKEditor controls. To use a different list, assign a new array to FontNames instead of changing the items of this array.

Example:

Adding a font to the default list:

this.ckEditor1.FontNames = CKEditor.DefaultFontNames.Concat(new[] { "Roboto" }).ToArray();

Enabled

Boolean: Returns or sets whether the control is enabled. (Default: True)

This property hides Enabled and is mapped to the inverse of ReadOnly: setting Enabled to false doesn't disable the control, it makes the editor read-only. Reading Enabled always returns the opposite of ReadOnly.

Example:

The two statements below have the same effect:

this.ckEditor1.Enabled = false;

// is the same as:
this.ckEditor1.ReadOnly = true;

ExternalPlugins

ExternalPlugin[]: Collection of external (local) plugins to register with the CKEditor control. (Default: null)

Each plugin is registered with CKEDITOR.plugins.addExternal() before the editor is created. Registering a plugin doesn't load it: add its Name to the extraPlugins option in Options (a comma separated list) to use it. Plugins with an empty Name, Url or FileName are ignored. Relative URLs are resolved against the URL of the application.

Example:

Registering and loading a plugin deployed with the application in /Plugins/timestamp/plugin.js:

this.ckEditor1.Options.extraPlugins = "timestamp";
this.ckEditor1.ExternalPlugins = new[]
{
    new ExternalPlugin
    {
        Name = "timestamp",
        Url = "Plugins/timestamp/",
        FileName = "plugin.js"
    }
};

FontNames

String[]: Returns or sets the font names to display in the toolbar.

The names are passed to CKEditor's font_names configuration. Each entry can be a single font name or a "Display Name/font-family list" pair, which shows the display name in the font list and applies the font-family list to the text. Set it to null or to an empty array to use the built-in font list of CKEditor. The default value is DefaultFontNames. Changing this property re-creates the editor.

Example:

Showing a mix of plain font names and named font stacks:

this.ckEditor1.FontNames = new[]
{
    "Arial",
    "Georgia",
    "Sans Serif/Helvetica Neue, Helvetica, Arial, sans-serif",
    "Monospace/Consolas, Courier New, monospace"
};

InitScript

String: Overridden to create our initialization script.

The script is generated from the properties of the control. This property is used by the framework and is not meant to be set by the application: assigned values are ignored.

Options

Object: Returns or sets the CKEDITOR.config to use for this instance of the editor: CKEDITOR. Use the toolbar configuration tool at index and copy the json into the Options definition.

The members of this dynamic object are sent to the client as-is and passed to CKEditor as its configuration object, so the member names must match the CKEDITOR.config names exactly (they are case sensitive).

Assigning a new object to Options re-creates the editor. Setting a member of the existing object (i.e. ckEditor1.Options.language = "fr") doesn't notify the control: call Update afterwards when the editor is already displayed.

The control always sets resize_enabled to false, sets allowedContent to true when it's not specified, and replaces versionCheck with the value of VersionCheck. The font list is set by FontNames.

Example:

Configuring the language, the color and a custom toolbar:

dynamic options = new Wisej.Core.DynamicObject();
options.language = "de";
options.uiColor = "#E8F0FE";
options.removeButtons = "Subscript,Superscript";
options.toolbar = new object[]
{
    new { name = "basicstyles", items = new[] { "Bold", "Italic", "Underline", "-", "RemoveFormat" } },
    new { name = "paragraph", items = new[] { "NumberedList", "BulletedList", "-", "Outdent", "Indent" } },
    "/",
    new { name = "links", items = new[] { "Link", "Unlink" } }
};

this.ckEditor1.Options = options;

Changing a single option of an editor that is already displayed:

this.ckEditor1.Options.language = "fr";
this.ckEditor1.Update();

Packages

List<Package>: Overridden to return our list of script resources.

Returns the "ckeditor.js" package loaded from BaseUrl. This property is used by the framework to load the CKEditor library and it's not meant to be used by the application.

ReadOnly

Boolean: Returns or sets whether the user can interact with the editor. (Default: False)

When true, the content cannot be edited and the editing commands in the toolbar are disabled. Changing this property doesn't re-create the editor. Enabled returns the inverse of this property.

ShowFooter

Boolean: Shows or hides the footer panel. (Default: True)

The footer panel shows the path of the HTML elements at the caret position. Hiding it removes the "elementspath" plugin from the editor configuration. Changing this property after the editor is displayed re-creates the editor on the client using the current Text.

ShowToolbar

Boolean: Shows or hides the toolbar panel. (Default: True)

Changing this property after the editor is displayed re-creates the editor on the client using the current Text.

Text

String: Returns or sets the HTML text associated with this control. (Default: "")

Value: The HTML text associated with this control.

The value is HTML markup, not plain text. Setting it replaces the content of the editor and fires the TextChanged event. Changes made by the user are sent back to the server when the editor loses the focus or with the next request that carries the state of the control. CKEditor may normalize the markup (for example, wrapping loose text in a paragraph), so the value read back can differ from the value that was assigned.

Example:

Loading HTML into the editor and reading it back when it changes:

this.ckEditor1.Text = "<h1>Title</h1><p>Some <strong>bold</strong> text.</p>";

private void ckEditor1_TextChanged(object sender, EventArgs e)
{
    this.labelSize.Text = $"{this.ckEditor1.Text.Length} characters of HTML";
}

VersionCheck

Boolean: Returns or sets the version check alert. (Default: False)

Maps to CKEditor's versionCheck configuration. When true, CKEditor checks whether the loaded version is up to date and secure and shows a notification in the editor when it isn't. This value always replaces versionCheck in Options. Changing this property re-creates the editor.

Methods

DisableCommand(command)

Disables the specified command on the toolbar.

Parameter	Type	Description
command	String	The name of the command to disable: i.e. "save", "bold", ...

The command name is the CKEditor command name (case sensitive), not the name of the toolbar button. An empty string and unknown commands are ignored. The state is remembered and applied again when the editor is re-created, for example when the page is refreshed. Use EnableCommand to enable the command again. To prevent all editing, use ReadOnly instead.

Throws:

ArgumentNullException command is null.

Example:

Preventing the user from editing the HTML source or printing the document:

this.ckEditor1.DisableCommand("source");
this.ckEditor1.DisableCommand("print");

EnableCommand(command)

Enables the specified command on the toolbar.

Parameter	Type	Description
command	String	The name of the command to enable: i.e. "save", "bold", ...

Throws:

ArgumentNullException command is null.

Example:

Enabling the Save button only after the content has changed:

private void Form1_Load(object sender, EventArgs e)
{
    this.ckEditor1.DisableCommand("save");
}

private void ckEditor1_TextChanged(object sender, EventArgs e)
{
    this.ckEditor1.EnableCommand("save");
}

ExecCommand(command, argument)

Executes commands to manipulate the contents of the editable region.

Parameter	Type	Description
command	String	The name of the CKEditor command to execute, i.e. "bold", "undo", "selectAll", "removeFormat". Command names are case sensitive and depend on the plugins loaded in the editor. See CKEDITOR_editor.
argument	String	For commands which require an input argument, this is a string providing that information. Specify null if no argument is needed.

Most commands affect the current selection (bold, italics, etc.), while others insert new elements (adding a link) or affect an entire line (indenting). If the editor is not ready yet, the command is executed as soon as it's initialized.

The Text property is updated asynchronously shortly after the command runs, so the new HTML is not available in the same server call that invoked ExecCommand. Executing a command also fires the Command event.

Example:

Executing commands from buttons outside of the editor:

private void buttonBold_Click(object sender, EventArgs e)
{
    this.ckEditor1.ExecCommand("bold");
}

private void buttonClearFormat_Click(object sender, EventArgs e)
{
    this.ckEditor1.ExecCommand("selectAll");
    this.ckEditor1.ExecCommand("removeFormat");
}

OnCommand(e)

Fires the Command event.

Parameter	Type	Description
e	CommandEventArgs

OnLinkClicked(e)

Fires the LinkClicked event.

Parameter	Type	Description
e	LinkClickedEventArgs

OnWebUpdate(state)

Updates the client component using the state information.

Parameter	Type	Description
state	Object	Dynamic state object.

OnWidgetEvent(e)

Fires the WidgetEvent event.

Parameter	Type	Description
e	WidgetEventArgs	A WidgetEventArgs that contains the event data.

Update()

Updates the client component.

Overridden to apply again the commands enabled or disabled with EnableCommand and DisableCommand when the client widget is re-created. Call this method after changing members of the existing Options object, which doesn't notify the control on its own. When the configuration has changed, the editor is re-created on the client using the current Text.

Example:

Applying new options to an editor that is already displayed:

this.ckEditor1.Options.language = "fr";
this.ckEditor1.Options.uiColor = "#FFF3E0";
this.ckEditor1.Update();

Events

Command

CommandEventHandler Fired after the editor executes a command.

The event is fired for commands executed from the toolbar, from keyboard shortcuts (i.e. Ctrl+B) and from ExecCommand. Command is the CKEditor command name, i.e. "bold", "save", "undo". The "applyFormatting" command is not reported because CKEditor fires it too often.

Example:

Handling the Save and Source buttons of the toolbar on the server:

this.ckEditor1.Command += ckEditor1_Command;

private void ckEditor1_Command(object sender, CommandEventArgs e)
{
    switch (e.Command)
    {
        case "save":
            SaveDocument(this.ckEditor1.Text);
            AlertBox.Show("Document saved.");
            break;

        case "source":
            this.labelStatus.Text = "Switched between design and HTML source view.";
            break;
    }
}

LinkClicked

LinkClickedEventHandler Fired after a link is clicked in the editor.

Link is the value of the href attribute as it's written in the HTML, so it can be a relative URL, an anchor (#section) or a "mailto:" link. Clicking a link in the editor doesn't navigate to it, use this event to open it. The event is fired only when the clicked element itself has an href attribute: clicking formatted text inside a link (i.e. a bold word) doesn't fire it. It's not fired at design time.

Example:

Opening the clicked link in a new browser tab:

this.ckEditor1.LinkClicked += ckEditor1_LinkClicked;

private void ckEditor1_LinkClicked(object sender, LinkClickedEventArgs e)
{
    if (e.Link.StartsWith("http://") || e.Link.StartsWith("https://"))
        Application.Navigate(e.Link, "_blank");
}

Implements

Name	Description
IUserData
IBindableComponent
IDropTarget
IWisejComponent
IWisejControl
IWisejHandler
IWisejSerializable

Constructors​

CKEditor()​

Properties​

BaseUrl​

DefaultFontNames​

Enabled​

ExternalPlugins​

FontNames​

InitScript​

Options​

Packages​

ReadOnly​

ShowFooter​

ShowToolbar​

Text​

VersionCheck​

Methods​

DisableCommand(command)​

EnableCommand(command)​

ExecCommand(command, argument)​

OnCommand(e)​

OnLinkClicked(e)​

OnWebUpdate(state)​

OnWidgetEvent(e)​

Update()​

Events​

Command​

LinkClicked​

Implements​

Constructors

CKEditor()

Properties

BaseUrl

DefaultFontNames

Enabled

ExternalPlugins

FontNames

InitScript

Options

Packages

ReadOnly

ShowFooter

ShowToolbar

Text

VersionCheck

Methods

DisableCommand(command)

EnableCommand(command)

ExecCommand(command, argument)

OnCommand(e)

OnLinkClicked(e)

OnWebUpdate(state)

OnWidgetEvent(e)

Update()

Events

Command

LinkClicked

Implements