Annotation of kupuMPIWG/doc/EXTENDING.txt, revision 1.1
1.1 ! dwinter 1: ==============
! 2: Extending Kupu
! 3: ==============
! 4:
! 5: XXX this document needs a major overhaul
! 6: XXX we should cover the the typical process of implementing a new feature
! 7: XXX writing a new implementation of features -> INTEGRATING.txt
! 8:
! 9: Abstract
! 10: --------
! 11:
! 12: This document describes the typical process of extending Kupu with a
! 13: new feature, such as a toolbox with the underlying functionality.
! 14: Both, the ECMAScript API and the templating system are explained.
! 15:
! 16: 1. Kupu Tools
! 17: -------------
! 18:
! 19: Apart from the context menu, all UI functionality in Kupu is added to
! 20: the core using a simple plugin mechanism. This can also be used to
! 21: write your own extensions, either by copying existing tools and
! 22: modifying them or by subclassing KupuTool (and sometimes KupuToolBox)
! 23: and writing your own functionality.
! 24:
! 25: 2. Tool interface
! 26: -----------------
! 27:
! 28: The plugins have a simple interface to adhere to:
! 29:
! 30: interface KupuTool:
! 31:
! 32: attribute toolboxes = {};
! 33: - id -> toolbox mapping
! 34:
! 35: method initialize(editor):
! 36: - store reference to the editor, register event handlers, etc.
! 37:
! 38: method registerToolBox(id, toolbox):
! 39: - register a UI element (ToolBox, more about those later)
! 40:
! 41: method updateState(selNode, event):
! 42: - update the state of self and any toolboxes
! 43:
! 44: method createContextMenuElements(selNode, event) (optional):
! 45: - return an array of ContextMenuElements
! 46:
! 47: 3. Writing a simple tool
! 48: ------------------------
! 49:
! 50: As an example we'll write our first simple tool, which displays the
! 51: path to the current node in the tree in the status bar. This is an
! 52: actual tool in the current Kupu code and you can see the result in the
! 53: status bar of any default Kupu installation. First we'll write a
! 54: class, and add a method called 'updateState' that will change the
! 55: status bar::
! 56:
! 57: // Example tool class
! 58: function ExampleTool() {
! 59: this.updateState = function(selNode, event) {
! 60: };
! 61: };
! 62:
! 63: The updateState method is a method each tool can implement (actually
! 64: the code assumes it's available on each tool, but since the superclass
! 65: defines it as well it's not strictly necessary to add it to your
! 66: class) and that will be called when the user clicks inside the iframe,
! 67: presses enter or hits a cursor key (so basically, when the cursor can
! 68: end up in a different element).
! 69:
! 70: As you can see we use in-line methods in Kupu, this is a choice of
! 71: style rather than for a functional reason, and if you wish you can
! 72: choose to use another coding style. Using
! 73: '<class>.prototype.<method> = function() {...};' will do equally well.
! 74:
! 75: Now we'll add some functionality to our updateState method. The
! 76: updateState method's first argument will always be a reference to the
! 77: current selected element (or the element currently containing the
! 78: selection). To get a path to that element from the root, we can write
! 79: something like::
! 80:
! 81: // Example tool class
! 82: function ExampleTool() {
! 83: /* shows the path to the current element in the status bar */
! 84: this.updateState = function(selNode, event) {
! 85: /* calculate and display the path */
! 86: var path = '';
! 87: var currnode = selNode;
! 88: while (currnode.nodeName != '#document') {
! 89: path = '/' + currnode.nodeName.toLowerCase() + path;
! 90: currnode = currnode.parentNode;
! 91: };
! 92:
! 93: window.status = path;
! 94: };
! 95: };
! 96:
! 97: The second argument is the event, if any, which started the
! 98: updateState chain (this doesn't have to be available, since
! 99: updateState can also be called by tools in certain situations).
! 100:
! 101: Now that we have the updateState method complete, we have the
! 102: functionality we wanted available. To make sure the tool provides all
! 103: functionality required by the system, the tool should subclass
! 104: KupuTool. This is not strictly required, but is a nice way to provide
! 105: all the methods the editor requires to be available.
! 106:
! 107: // subclass KupuTool
! 108: ExampleTool.prototype = new KupuTool;
! 109:
! 110: To hook the tool up with the editor, it needs to be registered. For
! 111: this purpose the registerTool method is available on the KupuEditor
! 112: object, which should be called with an id and a tool as arguments
! 113: (note that the KupuEditor is called 'kupu' here, like in the default
! 114: initKupu function, where registration of our tool will most likely be
! 115: done)::
! 116:
! 117: var exampletool = new ExampleTool();
! 118: kupu.registerTool('exampletool', exampletool);
! 119:
! 120: That's it, we just wrote a replacement for (or actually a copy of) the
! 121: ShowPathTool, the most basic Kupu tool.
! 122:
! 123: 4. A more complex example
! 124: -------------------------
! 125:
! 126: Now we'll take a look at a more complex example: the ImageTool. This
! 127: will provide a way for users to add images to the iframe. First thing
! 128: we do is write a class like we did for the example tool::
! 129:
! 130: function ImageTool() {
! 131: this.initialize = function(editor) {
! 132: this.editor = editor;
! 133: this.editor.logMessage('Image tool initialized');
! 134: };
! 135: };
! 136:
! 137: As you can see we override the superclass' initialize method, we don't
! 138: strictly have to here, but it's a custom to send a message to the log
! 139: window telling the user the tool has initialized, and it shows us how
! 140: a reference to the editor object is stored on the tool and used to
! 141: call logMessage on (which in turn calls the logger registered in
! 142: initKupu).
! 143:
! 144: Now let's add some functionality to the tool::
! 145:
! 146: function ImageTool() {
! 147:
! 148: // this will be required for later use, when the toolbox is added
! 149: this.toolboxes = {};
! 150:
! 151: this.initialize = function(editor) {
! 152: this.editor = editor;
! 153: this.editor.logMessage('Image tool initialized');
! 154: };
! 155:
! 156: this.createImage = function(url) {
! 157: /* insert an image */
! 158: this.editor.execCommand('InsertImage', url);
! 159: this.editor.logMessage('Image inserted');
! 160: };
! 161: };
! 162:
! 163: This method calls 'execCommand' on the editor object, which in turn
! 164: calls execCommand on the iframe (actually there's another step, but
! 165: that's not important now). execCommand is a built-in method provided
! 166: by browsers, that provides a limited amount of commands to WYSIWYG
! 167: editor applications. The InsertImage command will, as you may have
! 168: guessed, insert an image at the cursor location.
! 169:
! 170: All that is left to turn the tool into an Kupu Tool is set the prototype::
! 171:
! 172: ImageTool.prototype = new KupuTool;
! 173:
! 174: register it to the editor (in initKupu or the HTML page)::
! 175:
! 176: var imagetool = new ImageTool();
! 177: kupu.registerTool('imagetool', imagetool);
! 178:
! 179: and we're done with the basic tool.
! 180:
! 181: 5. ToolBoxes
! 182: ------------
! 183:
! 184: Now we have a class with a method that is capable of inserting an
! 185: image, but no way to call the method yet. The most basic way to call
! 186: the method would be from an HTML button, so we could simply create an
! 187: HTML button that would call the method. For larger tools, however,
! 188: it's nice to attach the event handlers from the code rather then from
! 189: the HTML itself, keeps things neat and clean, but on the other hand
! 190: it's nasty to have references to UI elements in the classes that
! 191: contain the functionality, for instance since someone using your tool
! 192: may want to use an element with another event or interface, or perhaps
! 193: even a completely different type of input (e.g. the context menu
! 194: mentioned below). Therefore we want another abstraction layer,
! 195: toolboxes.
! 196:
! 197: A ToolBox is basically a UI part of a Tool, containing references to
! 198: the HTML elements and containing and registering event handlers. For
! 199: the image tool we'd probably want a class with a reference to 2 HTML
! 200: elements: an input field to enter a URL in and a button to click on to
! 201: create the image::
! 202:
! 203: function ImageToolBox(inputel, buttonel) {
! 204: this.inputel = inputel;
! 205: this.buttonel = buttonel;
! 206:
! 207: this.initialize(tool, editor) {
! 208: // always store the references to the tool and editor
! 209: this.tool = tool;
! 210: this.editor = editor;
! 211:
! 212: // addEventHandler registers an event handler in both IE and
! 213: // Mozilla, last argument is the context in which to call the
! 214: // method
! 215: addEventHandler(this.button, 'click', this.createImage, this);
! 216: };
! 217:
! 218: this.createImage = function() {
! 219: var src = this.inputel.value;
! 220: if (!src) {
! 221: this.editor.logMessage('No image created since no URL was ' +
! 222: 'specified');
! 223: return;
! 224: };
! 225: this.tool.createImage(src);
! 226: };
! 227: };
! 228:
! 229: We don't create an updateState method here, although we could, since
! 230: we don't have a way to change the image's src attribute anyway. The
! 231: updateState method of toolboxes will usually update the state of the
! 232: UI elements of the tool (as happens with the TableTool, when inside a
! 233: tool you will see editing elements, when you're not inside one you'll
! 234: find elements to add a new table) or set the value of certain form
! 235: fields (as in the LinkTool, when inside a link it will show you the
! 236: href of the link), both not appropriate in this case (although a
! 237: usecase could easily be written I would say ;).
! 238:
! 239: 6. ContentFilters
! 240: -----------------
! 241:
! 242: Before Kupu sends its contents to the server, it is converted from
! 243: HTML to XHTML and then passed through any registered content filters.
! 244:
! 245: Content filters are simple classes that should have 2 methods::
! 246: initialize, which will be called on registration of the filter, with a
! 247: single argument which is a reference to the editor, and filter, which
! 248: will be called with 2 arguments: a reference to the owner document
! 249: (the document element of the iframe) and the html node of the
! 250: document. The idea is that the filter should use DOM functionality to
! 251: filter the incoming DOM and return the filtered version. To register
! 252: a content filter to Kupu, use 'kupu.registerFilter(filter)'.
! 253:
! 254: The XHTML conversion is configurable. By default it accepts any tags
! 255: defined in XHTML 1.0 transitional, as well as any attributes except
! 256: for the event attributes (those beginning with 'on'). Tags not in the
! 257: html namespace are stripped.
! 258:
! 259: A tag is permitted if it is defined in XHTML and not blacklisted.
! 260: Optionally kupu can also filter to maintain a valid XHTML nesting of
! 261: tags, but this option is off by default (put a
! 262: `<filterstructure>1</filterstructure>` tags into the htmlfilter
! 263: configuration to turn it on, or set `editor.xhtmlvalid.filterstructure`
! 264: to true. When the structure filtering is turned on a tag is permitted
! 265: if it is allowed within the current context (e.g. you cannot nest `<A>`
! 266: tags directly inside other `<A>` tags, so any nested `<A>` tags will be
! 267: stripped). If a tag is stripped its content will still be present. An
! 268: attribute is permitted if it is defined in XHTML and not blacklisted
! 269: for that tag. Text data is stripped if it occurs in a context not
! 270: valid in XHTML (e.g. inside a table but outside `<TH>` or `<TD>`).
! 271:
! 272: The blacklist is taken from Kupu's xml configuration. An `<htmlfilter>` tag
! 273: encloses the blacklist, `<t>` marks a tag to be blacklisted, <a> marks
! 274: an attribute to be blacklisted, `<c>` marks attributes to be excluded
! 275: for specific tags. e.g. the following would blacklist the `center`
! 276: and `font` tags, the `cellspacing` attribute everywhere, and the
! 277: `width` attribute for the `th` and `td` tags only. ::
! 278:
! 279: <htmlfilter>
! 280: <t>center></t><t>font</t>
! 281: <a>cellspacing</a>
! 282: <c><t>th</t><t>td</t><a>width</a></c>
! 283: </htmlfilter>
! 284:
! 285: From Javascript you can use the excludeAttributes, excludeTags and
! 286: excludeTagAttributes methods of `editor.xhtmlvalid` to get the same
! 287: effect.
! 288:
! 289: The `style` attribute filters its content to permit `text-align` and
! 290: `list-style-type` styles and reject all others (these styles are used
! 291: by kupu). The style whitelist may be extended by adding additional
! 292: entries to `editor.xhtmlvalid.styleWhitelist`.
! 293:
! 294: The `class` attribute is filtered to reject classnames which appear in
! 295: the class blacklist. Add entries to `editor.xhtmlvalid.classBlacklist`
! 296: to reject additional classes.
! 297:
! 298: Entries may be added to the style whitelist or the class blacklist
! 299: through the `<htmlfilter>` section of the configuration::
! 300:
! 301: <htmlfilter>
! 302: ... as above ...
! 303: <style>list-style-image</style>
! 304: <class>badClassName</class>
! 305: </htmlfilter>
! 306:
! 307: Additional attributes may be added to existing tags by calling the
! 308: `setTagAttributes` and `setAttrFilter` methods. e.g. ::
! 309:
! 310: editor.xhtmlvalid.setTagAttributes(['div'], ['special']);
! 311: editor.xhtmlvalid.setAttrFilter(['special']);
! 312:
! 313: adds an attribute `special` to the `div` tag. The method tags three
! 314: parameters: a list of attributes, a list of tags, and optionally a
! 315: filter method to be called for that attribute. If the filter method is
! 316: omitted the attribute is simply copied.
! 317:
! 318: The validation API is as follows (for the purposes of this api, a
! 319: `dict` means an object whose property names are the dict keys):
! 320:
! 321: Set
! 322: a javascript class used to quickly create a 'dict' where all
! 323: the values are 1. The constructor takes a single keyname, or a list
! 324: of keynames, or a Set.
! 325:
! 326: attrFilters
! 327: a dict keyed by attributeName, of filter functions for each
! 328: attribute. Any attribute not in this dict is invalid.
! 329:
! 330: tagAttributes
! 331: a dict keyed by tagName, of arrays of valid attribute names for
! 332: each tag. Any tag not in this dict is invalid. N.B. Tags which share
! 333: a common set of attributes may be sharing the same array.
! 334:
! 335: All attributeNames in the sets in tagAttributes must exist in
! 336: attrFilters.
! 337:
! 338: setAttrFilter(attributes,filter)
! 339: sets the filter function in attrFilters for the list of attributes,
! 340: adding the attributes if they don't already exist. A simple copy
! 341: function is used if filter is not provided.
! 342:
! 343: setTagAttributes(tags,attributes)
! 344: for each tag in the list of tags, sets tagAttributes[tag] to the list of
! 345: attributes. An empty list of attributes is used if attributes is
! 346: omitted.
! 347:
! 348: includeTagAttributes(tags, attributes)
! 349: for each tag in the list of tags, adds the list of attributes to
! 350: tagAttributes[tag]
! 351:
! 352: excludeTagAttributes(tags, attributes)
! 353: for each tag in the list of tags, removes any attribute in the list
! 354: of attributes from the list in tagAttributes[tag].
! 355:
! 356: excludeTags(tags)
! 357: removes the list of tags from tagAttributes.
! 358:
! 359: excludeAttributes(attributes)
! 360: removes the set of attributes from attrFilters and all tags in
! 361: tagAttributes.
! 362:
! 363: styleWhitelist
! 364: a Set. Each key is the css name of a style. e.g. text-align.
! 365: Only those elements of the style attribute which are present in this
! 366: set are permitted through the filtering.
! 367: The default setting includes only those styles which may be set by
! 368: kupu.
! 369:
! 370: classBlacklist
! 371: a Set. Each key is a classname which should not be permitted. All
! 372: other classnames are allowed through the filtering. The default
! 373: setting is a list of styles likely to be present when a pasting text
! 374: copied out of Microsoft Word.
! 375:
! 376:
! 377: 7. Loggers
! 378: ----------
! 379:
! 380: Loggers are classes to log messages. A logger will usually do nothing,
! 381: or at most send everything to some text area or div, unless an error
! 382: log message comes in, in which case most loggers will probably raise
! 383: an exception. Loggers should have a single method called 'log' that
! 384: gets one mandatory and one optional argument: it must get a message
! 385: (which is a string that will, or in some cases will not, get logged)
! 386: and it may get a severity argument, which can be 0 for debug messages,
! 387: 1 for warnings and 2 for errors. The default should be 0.
! 388:
! 389: A logger should be passed to the editor on instantiation time (it's
! 390: one of the constructor's arguments).
! 391:
! 392: 8. And the rest
! 393: ---------------
! 394:
! 395: Of course there's a lot more to Kupu that can be customized, added or
! 396: rewritten. For more details see the source: it should be quite clear
! 397: and simple and is written in a nice object oriented manner. Also make
! 398: sure to check out JSAPI.txt, which is a reference to Kupu' JavaScript
! 399: JSAPI.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/cvs/cvsweb/icons/back.gif){kind=icon}
Return to EXTENDING.txt CVS log ![[TXT]](/cvs/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvs/cvsweb/icons/dir.gif){kind=icon}
Up to [Repository] / kupuMPIWG / doc