Customizing WYMeditor

Note

If you’re more of a “Learning by Doing” person, there are tons of hosted examples to try out if you’re looking for ideas. You can use View Source from there or look in the examples/ directory of your WYMeditor repository or distribution.

Basics of Customization

There are four primary methods of customizing WYMeditor. All of them come down to passing in options on editor initialization and possibly including extra javascript and CSS on your page. The methods are:

1. Using WYMeditor Initialization Options

Using WYMeditor Options is the easiest method of customization and the most common. By changing the proper WYMeditor Options, you can change the user interface’s skin, choose from a wide range of plugins, add or remove items from the toolbar, include custom CSS classes for your users to choose and lots more.

2. Using a WYMeditor “Skin”

We use WYMeditor Skins to package up user interface tweaks and customizations. There are many included options from which to choose along with the ability to write your own.

3. Using WYMeditor Plugins

By Using WYMeditor Plugins you can enable a broad range of extra behaviors. If none of the Included Plugins with Download meet your needs, there’s a range of Third Party Plugins available.

Note

Still can’t find what you need? No problem. We have documentation for writing_plugins/index too.

4. Using a Custom Iframe

If you’d like to make tweaks to the way that your content looks inside the editor (the part with the blue background), then you can also choose a custom iframe. Check out the wymeditor/iframes directory for some existing options, or roll your own.

Using WYMeditor Options

All WYMeditor Options are set by passing an options object as the only parameter to the WYMeditor initialization function.

$(".my-wymeditor-class").wymeditor(options)

Example: Start with Existing HTML and Alert on Load

Let’s say you want to edit some existing HTML and then annoy your users with an alert box. You’ve got a mean streak, but we can absolutely do that.

The postInit option lets us define a callback after initialization and the editor is automatically initialized with the contents of its textarea element. Our options object should look like this:

var options = {
    postInit: function() {
        alert('OK');
    }
};

Full HTML

Our stripped-down full example then looks like this:

<html>
<head>
    <link rel="stylesheet" type="text/css" href="wymeditor/wymeditor.css" />
</head>

<body>
    <form method="post" action="">
        <textarea class="my-wymeditor-class">
            &lt;p&gt;Hello, World!&lt;/p&gt;
        </textarea>
        <input type="submit" class="wymupdate" />
    </form>

    <script type="text/javascript" src="jquery/jquery.js"></script>
    <script type="text/javascript" src="wymeditor/jquery.wymeditor.js"></script>
    <script type="text/javascript">
        $(function() {
            var options = {
                postInit: function() {
                    alert('OK');
                }
            };
            jQuery(".wymeditor").wymeditor(options);
    </script>
</body>
</html>

WYMeditor Options

Note

All options and their defaults are located in wymeditor/core.js in the jQuery.fn.wymeditor method. Though if they’re not documented here, they’re subject to change between releases without following our deprecation policy.

Common Options

html

Initializes the editor’s HTML content.

Example
html: "<p>Hello, World!<\/p>"

As an alternative, you can just fill the textarea WYMeditor is replacing with the initial HTML.

lang

The language to use with WYMeditor. Default is English (en). Codes are in ISO-639-1 format.

Language packs are stored in the wymeditor/lang directory.

Example: Choosing the Polish Translation

To use the Polish translation instead, use the value pl.

$('.wymeditor').wymeditor({
    lang: 'pl'
});

toolsItems

An array of tools buttons, inserted in the tools panel, in the form of:

[
    {
        'name': 'value',
        'title': 'value',
        'css': 'value'
    }
]
Example
toolsItems: [
  {'name': 'Bold', 'title': 'Strong', 'css': 'wym_tools_strong'},
  {'name': 'Italic', 'title': 'Emphasis', 'css': 'wym_tools_emphasis'}
]
Default value
toolsItems: [
  {'name': 'Bold', 'title': 'Strong', 'css': 'wym_tools_strong'},
  {'name': 'Italic', 'title': 'Emphasis', 'css': 'wym_tools_emphasis'},
  {'name': 'Superscript', 'title': 'Superscript', 'css': 'wym_tools_superscript'},
  {'name': 'Subscript', 'title': 'Subscript', 'css': 'wym_tools_subscript'},
  {'name': 'InsertOrderedList', 'title': 'Ordered_List', 'css': 'wym_tools_ordered_list'},
  {'name': 'InsertUnorderedList', 'title': 'Unordered_List', 'css': 'wym_tools_unordered_list'},
  {'name': 'Indent', 'title': 'Indent', 'css': 'wym_tools_indent'},
  {'name': 'Outdent', 'title': 'Outdent', 'css': 'wym_tools_outdent'},
  {'name': 'Undo', 'title': 'Undo', 'css': 'wym_tools_undo'},
  {'name': 'Redo', 'title': 'Redo', 'css': 'wym_tools_redo'},
  {'name': 'CreateLink', 'title': 'Link', 'css': 'wym_tools_link'},
  {'name': 'Unlink', 'title': 'Unlink', 'css': 'wym_tools_unlink'},
  {'name': 'InsertImage', 'title': 'Image', 'css': 'wym_tools_image'},
  {'name': 'InsertTable', 'title': 'Table', 'css': 'wym_tools_table'},
  {'name': 'Paste', 'title': 'Paste_From_Word', 'css': 'wym_tools_paste'},
  {'name': 'ToggleHtml', 'title': 'HTML', 'css': 'wym_tools_html'},
  {'name': 'Preview', 'title': 'Preview', 'css': 'wym_tools_preview'}
]

containersItems

An array of containers buttons, inserted in the containers panel in the form of:

[
    {
        'name': 'value',
        'title': 'value',
        'css': 'value'
    }
]
Example
containersItems: [
  {'name': 'P', 'title': 'Paragraph', 'css': 'wym_containers_p'},
  {'name': 'H1', 'title': 'Heading_1', 'css': 'wym_containers_h1'}
]

classesItems

An array of classes buttons, inserted in the classes panel in the form of:

[
    {
        'name': 'value',
        'title': 'value',
        'expr': 'value'
    }
]

expr is a jQuery selector that allows you to control to which elements the class defined by name can be applied. Only elements matching the selector expr will be given the class on a user’s click.

Example

Let’s support adding the class date to paragraphs, and the class hidden-note to paragraphs that don’t already have the class important.

classesItems: [
  {'name': 'date', 'title': 'PARA: Date', 'expr': 'p'},
  {'name': 'hidden-note', 'title': 'PARA: Hidden note', 'expr': 'p[@class!="important"]'}
]

preInit

A custom function which will be executed directly before WYMeditor’s initialization.

Parameters
  • wym: the WYMeditor instance

preBind

A custom function which will be executed directly before handlers are bound on events (e.g. buttons click).

Parameters
  • wym: the WYMeditor instance

postInit

A custom function which will be executed once, when WYMeditor is ready.

Parameters
  • wym: the WYMeditor instance
Example
postInit: function(wym) {
  //activate the 'tidy' plugin, which cleans up the HTML
  //'wym' is the WYMeditor instance
  var wymtidy = wym.tidy();
  wymtidy.init();
}

Uncommon Options

Most of these options are only required in abnormal deployments, or useful for deep customization.

Note

Any options not documented are considered private and are subject to change between releases without following the deprecation policy.

basePath

WYMeditor’s relative/absolute base path (including the trailing slash).

This value is automatically guessed by computeWymPath, which looks for the script element loading jquery.wymeditor.js.

Example
basePath: "/admin/edit/wymeditor/"

wymPath

WYMeditor’s main JS file path.

Similarly to basePath, this value is automatically guessed by computeBasePath.

iframeBasePath

The path to the directory containing the iframe that will be initialized inside the editor body itself.

This value is automatically guessed, based on the basePath value.

updateSelector and updateEvent

Note

Will be removed in 1.0. Instead, users should do their own event handling/registration and make a call to wym.update().

Allows you to update the value of the element replaced by WYMeditor (typically a textarea) with the editor’s content on .while e.g. clicking on a button in your page.

preInitDialog

A custom function which will be executed directly before a dialog’s initialization.

Parameters
  1. wym: the WYMeditor instance
  2. wdw: the dialog’s window object

postInitDialog

A custom function which will be executed directly after a dialog is ready.

Parameters
  1. wym: the WYMeditor instance
  2. wdw: the dialog’s window object

UI Customization Options

These options allow deep customization of the structure of WYMeditor’s user interface by changing the HTML templates used to generate various UI components. Rather than using these, most user’s prefer WYMeditor Skins.

List of HTML Template Options

  • boxHtml

  • logoHtml

  • iframeHtml

  • toolsHtml

  • toolsItemHtml

  • containersHtml

  • containersItemHtml

  • classesHtml

  • classesItemHtml

  • statusHtml

  • htmlHtml

  • dialogHtml

  • dialogLinkHtml

  • dialogFeatures The dialogs’ default features. e.g.

    dialogFeatures: "menubar=no,titlebar=no,toolbar=no,resizable=no,width=560,height=300,top=0,left=0"
    
  • dialogImageHtml

  • dialogTableHtml

  • dialogPasteHtml

  • dialogPreviewHtml

UI Selectors Options

These selectors are used internally by WYMeditor to bind events and control the user interface. You’ll probably only want to modify them if you’ve already changed one of the UI Customization Options.

List of Selectors

  • boxSelector
  • toolsSelector
  • toolsListSelector
  • containersSelector
  • classesSelector
  • htmlSelector
  • iframeSelector
  • statusSelector
  • toolSelector
  • containerSelector
  • classSelector
  • htmlValSelector
  • hrefSelector
  • srcSelector
  • titleSelector
  • altSelector
  • textSelector
  • rowsSelector
  • colsSelector
  • captionSelector
  • submitSelector
  • cancelSelector
  • previewSelector
  • dialogLinkSelector
  • dialogImageSelector
  • dialogTableSelector
  • dialogPasteSelector
  • dialogPreviewSelector
  • updateSelector

Example Selector Customization

classesSelector: ".wym_classes"