WYSIWYG Editor Module
WYSIWYG Editor Module
Contents
This page will show you how to integrate the WYSIWYG editor in your wiki pages and how to interact with it.
Integration
First, include the JavaScript code of the editor in your page like this:
$xwiki.jsfx.use("js/xwiki/wysiwyg/xwe/XWikiWysiwyg.js", true)
{{/velocity}}
This way the editor code is loaded when your page is loaded. If you want to use the WYSIWYG editor in an AJAX fashion i.e. load its code on demand, asynchronously, then write this instead:
$xwiki.jsfx.use("js/xwiki/wysiwyg/xwe/XWikiWysiwyg.js", {'forceSkinAction': true, 'lazy': true})
{{/velocity}}
This way the editor code is loaded after your first call to Wysiwyg.onModuleLoad. Note that some WYSIWYG editor plugins might require external JavaScript libraries which you have to include also. Alternatively use the wysiwyg_import velocity macro which takes care of this for you:
#set($lazy = false)
#wysiwyg_import($lazy)
{{/velocity}}
At this point the Wysiwyg object and the WysiwygEditor class should be ready to use.
...
<textarea id="demo"></textarea>
...
<script type="text/javascript">
Wysiwyg.onModuleLoad(function() {
new WysiwygEditor({hookId:'demo'});
});
</script>
...
{{/html}}
The editor can replace a plain HTML text area specified by its id. See the configuration page for a list of parameters that you can pass when creating a new editor instance.
JavaScript API
Wysiwyg
alert('WYSIWYG code is loaded!');
});
Methods
- load() : void
Loads the WYSIWYG code on demand. - onModuleLoad(fCode : function, lazy : boolean) : void
Schedules a function to be executed after the WYSIWYG module is loaded. A call to this method forces the WYSIWYG module to be loaded, unless the second parameter, lazy, is set to true.
WysiwygEditor
editor = new WysiwygEditor({hookId: 'content'});
});
Methods
- WysiwygEditor(config : Object) : WysiwygEditor
Creates a new editor based on the given configuration object. - release() : void
Releases the editor so that it can be garbage collected before the page is unloaded. Call this method before the editor is physically detached from the DOM document. - getPlainTextArea() : Object
Returns the plain HTML text area element used by the editor. - getRichTextArea() : Object
Returns the rich text area element used by the editor. - getSourceText(onSuccess : function, onFailure : function) : void
Sends a request to the server to convert the HTML output of the rich text editor to source text and calls one of the given functions when the response is received. - getCommandManager() : CommandManager
Use the returned object to execute commands on the editor and query their value.
CommandManager
editor.getCommandManager().execute('forecolor', 'yellow');
alert( editor.getCommandManager().getValue('forecolor') );
}
Methods
- execute(commandName : String, parameter : String) : boolean
Executes the specified command with the given parameter on the current selection in the rich text area. Returns true if the command was executed successfully, false otherwise. - getValue(commandName : String) : String
Returns the value of the specified command for the current selection in the rich text area. - isEnabled(commandName : String) : boolean
Returns true if the specified command can be executed on the current selection, false otherwise. - isExecuted(commandName : String) : boolean
Returns true if the specified command was executed on the current selection, false otherwise. - isSupported(commandName : String) : boolean
Returns true if the specified command is supported by the editor, false otherwise.
Custom events
alert('A new WYSIWYG editor has been created!');
});
- xwiki:wysiwyg:created
Fired after a WYSIWYG editor is successfully created. The new WYSIWYG editor instance is passed as an argument to the listener.
Examples
Load on demand and show source text
{{html}}
#wysiwyg_import(true)
<script type="text/javascript">
function loadOnDemand() {
Wysiwyg.onModuleLoad(function() {
editor = new WysiwygEditor({
hookId:'demo',
syntax: 'xwiki/2.0'
});
});
}
function showSourceText() {
if (typeof editor == 'undefined') {
alert('Load the editor first!');
} else {
editor.getSourceText(function onSuccess(result){
alert('Source: ' + result);
}, function(message) {
alert('Error: ' + message);
});
}
}
</script>
<div>
<button onclick="loadOnDemand()">Load Editor</button>
<button onclick="showSourceText()">Show source text</button>
</div>
<textarea id="demo"></textarea>
{{/html}}
{{/velocity}}
