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.
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:
customization-using-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.
We use /using_wymeditor/using_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.
By /using_wymeditor/using_plugins
you can enable a broad range of extra behaviors. If none of the /wymeditor_plugins/included_plugins/index
meet your needs, there's a range of /wymeditor_plugins/third_party_plugins/index
available.
Note
Still can't find what you need? No problem. We have documentation for writing_plugins/index
too.
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.
All wymeditor-options
are set by passing an options object as the only parameter to the WYMeditor initialization function.
$(".my-wymeditor-class").wymeditor(options)
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 option-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');
}
};
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">
<p>Hello, World!</p>
</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>
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.
Initializes the editor's HTML content.
html: "<p>Hello, World!<\/p>"
As an alternative, you can just fill the textarea WYMeditor is replacing with the initial HTML.
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.
To use the Polish translation instead, use the value pl
.
$('.wymeditor').wymeditor({
lang: 'pl'
});
An array of tools buttons, inserted in the tools panel, in the form of:
[
{
'name': 'value',
'title': 'value',
'css': 'value'
}
]
toolsItems: [
{'name': 'Bold', 'title': 'Strong', 'css': 'wym_tools_strong'},
{'name': 'Italic', 'title': 'Emphasis', 'css': 'wym_tools_emphasis'}
]
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'}
]
An array of containers buttons, inserted in the containers panel in the form of:
[
{
'name': 'value',
'title': 'value',
'css': 'value'
}
]
containersItems: [
{'name': 'P', 'title': 'Paragraph', 'css': 'wym_containers_p'},
{'name': 'H1', 'title': 'Heading_1', 'css': 'wym_containers_h1'}
]
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.
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"]'}
]
A custom function which will be executed directly before WYMeditor's initialization.
- wym: the WYMeditor instance
A custom function which will be executed directly before handlers are bound on events (e.g. buttons click).
- wym: the WYMeditor instance
A custom function which will be executed once, when WYMeditor is ready.
- wym: the WYMeditor instance
postInit: function(wym) {
//activate the 'tidy' plugin, which cleans up the HTML
//'wym' is the WYMeditor instance
var wymtidy = wym.tidy();
wymtidy.init();
}
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.
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
.
basePath: "/admin/edit/wymeditor/"
WYMeditor's main JS file path.
Similarly to option-basePath
, this value is automatically guessed by computeBasePath
.
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.
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.
A custom function which will be executed directly before a dialog's initialization.
- wym: the WYMeditor instance
- wdw: the dialog's window object
A custom function which will be executed directly after a dialog is ready.
- wym: the WYMeditor instance
- wdw: the dialog's window object
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 /using_wymeditor/using_skins
.
- 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
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 options-ui-customization-options
.
- 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
classesSelector: ".wym_classes"
examples/index