Toolbars
The idea of that RTE plugin for jQuery is - split core and toolbars functionality, but without any bloating core-api. So core can do only basic functions (read about it in API section).
Let's look for basic usage of plugin (turn any textarea with class 'rte' into WYSIWYG):
$('.rte').rte({
controls_rte: rte_toolbar,
controls_html: html_toolbar
});
As you can see there are 2 options: controls_rte and controls_html. Later you will know how to create it. Just remember, plugin has no any bult-in toolbars or controls by default. If you will use it without any options:
$('.rte').rte();
you will get next:
The only controls enable\disable as you see. It has built-in callback, but actually you can overwrite it (inherit, by other words. It's very useful for additional text-processing between switching of modes or before submit).
Ok, now you are really ready to create own controls.
= Creating Own Controls = Controls is javascript object actually, that has specific format. Format is simple, and probably suit for any task that you will want. Controls is the thing that you provide at startup/initialize step as 'controls_rte' and 'controls_html' inside of options. Look for example above.
{
*control_name1* : {...},
*control_name2* : {...},
*control_nameN* : {...}
}
*control_name*: {
*command:* string
*separator:* boolean
*init:* function
*exec:* function
*args:* string or array
*select:* string
*tag_cmp:* function
*hint*: string
*tags:* array
}
Where contol_name is name of your control. It's used as className for CSS-styling. This must be unique for each toolbar. Shortly: only one control with 'control_name' per toolbar.
s1: {separator: true}
bold: {command: 'bold', tags:['b', 'strong']}
bold: {
exec: function() {
var self = this;
alert("Control clicked!");
self.editor_cmd('bold');
},
hint: "New version of bold",
tags: ['b', 'strong']
}
Let's talk about each thing.
It's command for browser's design mode editor. Some commands need additional arguments (for example, name of font), some don't. It's browser specific feature.
command: 'formatBlock'
You can read more about that commands here:
http://msdn.microsoft.com/en-us/library/ms533049(VS.85).aspx
http://www.mozilla.org/editor/midas-spec.html
Just set it true, if you want to add new separator inside of your toolbar. Other parameters are omitted.
separator: true
Well, this is function that will be called before adding that control into the toolbar. So additional manipulations can be done. For example, dependence on 'args' of that control. Remember 'this' reference at that function is control, but not rte!
init: function(rte) {
alert("Control setup");
this.exec = function() { alert('on fly callback.') };
}
init: function(rte) {
if(this.args == 'arg1') {
this.exec = function() { alert('exec1.') };
} else {
this.exec = function() { alert('exec2.') };
}
alert(this.exec);
}
Well, this is a heart of you own specific control. Here you must place any functionality that you want from that control. To get instance of lwRTE object (to use core functions), you can use 'this' reference. If you provided 'args' for that control, than you can get it as argument 'args'. If contol is select, than last argument will be 'select' object, so you will be able to get index of selected item.
exec: function(args) {
alert("Hello world from that control");
}
exec: function(args) {
var self = this;
alert("You have selected:" + self.get_selected_text());
}
exec: function(args) {
var self = this;
var text = self.get_content();
text = text.replace( /<BR>/gi, '[BR]' );
self.set_content(text);
}
exec: function(args) {
var self = this;
self.editor_cmd('insertImage', 'uploads/screenshot.jpg');
}
exec: function(args) {
if(args) {
try {
var css = args.options[args.selectedIndex].value
var self = this;
var html = self.get_selected_text();
html = '<span class="' + css + '">' + html + '</span>';
self.selection_replace_with(html);
args.selectedIndex = 0;
} catch(e) {
}
}
}
Just look at 'jquery.rte.tb' inside of full package and you will see more complex, real functionality like file uploads, color selections and other.
Just additional arguments for 'command'. Read more about it at 'command' section (Check URLs for specification)
Sometimes you need not a common control, but a selection from few values, like font selection, for example. In that case you can provide a html-code for that selection here.
select: "
<select>\
<option value="">-</option>\
<option value="1">1 (8pt)</option>\
<option value="2">2 (10pt)</option>\
<option value="3">3 (12pt)</options>\
<option value="4">4 (14pt)</option>\
<option value="5">5 (16pt)</options>\
<option value="6">6 (18pt)</option>\
<option value="7">7 (20pt)</options>\
</select>\
"
This is callback function to compare DOM node and tag from tags parameter. It's using by core (set_selected_controls) to mark active controls on toolbar. Read more about it in API section. Shortly: node - is DOM object, tag - is value from tags array (read more below).
tag_cmp:
function(node, tag) {
tag = tag.replace(/<([^>]*)>/, '$1');
return (tag.toLowerCase() == node.nodeName.toLowerCase());
}
You can add extended hint for control that will be shown (core will set 'title' for common controls).
hint: 'Make you text bold'
This array is using by core (set_selected_controls) to mark active controls. Using with tag_cmp callback and core(set_selected_controls).
tags: ['b', 'strong']
Ok, for example, you need some additional text processing before submit and want to implement it easily? Not a problem. Just add any parameter you want (from documentation above) for enabled and disable controls. enable is using on source mode toolbar and disable is using on design mode toolbar. Don't care about turning on/off design mode, core will do rest things.
var rte_toolbar = {
disable: {
exec: function() { alert("Press OK to turn OFF design mode!"); }
}
};
var html_toolbar = {
enable: {
exec: function() { alert("Press OK to turn ON design mode!"); }
}
};
*Check source of basic toolbar to get more examples of controls*