Annotation of kupu/doc/JSAPI.txt, revision 1.1
1.1 ! dwinter 1: ==================
! 2: Kupu API reference
! 3: ==================
! 4:
! 5: Kupu can be customized in several ways: controls can be customized or
! 6: hidden using CSS, elements can be modified using TAL (modifying the
! 7: macro) and more advanced customization can be done by extending (or
! 8: modifying, although this is usually not advised) the JavaScript,
! 9: either in the macro or in seperate .js files. This document will give
! 10: a short description of how to use and extend the Kupu JavaScripts and
! 11: a reference of the public Kupu API.
! 12:
! 13:
! 14: How to use Kupu
! 15: ===============
! 16:
! 17: The KupuEditor and KupuUI objects
! 18: ---------------------------------
! 19:
! 20: Generally the body tag of the document will contain a call to the
! 21: initKupu function. This is the glue code of Kupu, here's where all the
! 22: objects get instantiated and tied together to form the
! 23: application. When doing large customizations, this function will
! 24: usually be overwritten or extended. The default implementation takes 1
! 25: argument (the id of the iframe it will control) and return a reference
! 26: to the core object, KupuEditor.
! 27:
! 28: kupu = initKupu("kupu-editorframe");
! 29:
! 30: The KupuEditor object (in this case called 'kupu') will be the object
! 31: with which you can control the iframe, the UI and
! 32: tools. Customizations should generally not involve extending the
! 33: KupuEditor object, but rather by plugging in new tools. Usage is quite
! 34: straightforward, for a reference of the public methods see below.
! 35:
! 36: The UI object holds event handlers for the toolbar buttons. This is a
! 37: core Kupu object and should generally be left untouched. The event
! 38: handlers, although the preferred method of attaching events is dynamic
! 39: from inside the objects rather then from HTML, should be attached to
! 40: the buttons from the template (this made the code a lot cleaner, it
! 41: might change in future versions though). Therefore a reference to the
! 42: UI object must be retrieved from the KupuEditor object using the
! 43: getTool method:
! 44:
! 45: kupuui = kupu.getTool('ui');
! 46:
! 47: Note that the reason why this method is called getTool is that the UI
! 48: is essentially treated as a tool, an Kupu plugin (more about those
! 49: later). The string 'ui' is the id by which the object is registered
! 50: in initKupu. Usually the ui object and the button bindings can just
! 51: be copied from the kupu.html file (if you don't use ZPT macros in the
! 52: kupumacros.html file).
! 53:
! 54: Tools and extending Kupu
! 55: ------------------------
! 56:
! 57: Tools are extensions of Kupu. A tool can be seen as a plugin in the
! 58: Kupu editor, providing additional functionality. Tools will usually be
! 59: the objects that will be extended or overridden.
! 60:
! 61: A tool should usually subclass KupuTool and will usually override the
! 62: 'initialize' method (which will be called when the tool is registered to
! 63: the KupuEditor object) and the updateState method (which will be
! 64: called on click and certain keyup events on the iframe so that the
! 65: state of the tool (e.g. add or edit mode) can be controlled. Events on
! 66: elements should generally be bound to the methods from inside the
! 67: tools.
! 68:
! 69: The initialize method will be called with a single argument, a
! 70: reference to the editor object. The method should at least store that
! 71: reference on this. Note that if you don't override the method, the
! 72: KupuObject class provides a default implementation that does exactly
! 73: that. The updateState method will be called with 2 arguments, the
! 74: first is a reference to the current selected element and the second
! 75: the event object. If the tool doesn't want to react to state changes,
! 76: it doesn't have to override the method: the superclass will provide a
! 77: dummy implementation.
! 78:
! 79: Usually a tool will be created and registered inside initKupu,
! 80: although it can also be done from an external document or the HTML. An
! 81: object is registered to the KupuEditor object as such:
! 82:
! 83: var myTool = new MyTool();
! 84: kupu.registerTool('my-tool', myTool);
! 85:
! 86: As shown above, the getTool method of the KupuEditor object can be
! 87: used to retrieve a reference to the tool later on (so there's no need
! 88: to store a reference in the global namespace or anything).
! 89:
! 90: For a nice, small example of a tool, see the PathTool in the
! 91: kupubasetools.js file.
! 92:
! 93: ToolBoxes and larger Tools
! 94: --------------------------
! 95:
! 96: Most tools will both harbour functionality and stuff like event handlers
! 97: and references to HTML elements. To make sure the tool can be used in as
! 98: much different situations as possible, it is advised to split it up in 2
! 99: pieces, one for the logic and one for the UI-related methods and
! 100: attributes.
! 101: The standard way for doing this is using a subclass of KupuTool for the
! 102: tool and a subclass of KupuToolBox for the UI-part, and register the ToolBox
! 103: to the Tool using the registerToolBox method. It is not mandatory to use
! 104: this baseclass, not even to use registerToolBox, but it should be sufficient.
! 105:
! 106: For a more complex (and useful) example of a Tool combined with a ToolBox
! 107: see the LinkTool.
! 108:
! 109: Public API
! 110: ==========
! 111:
! 112: Helper functions (kupuhelpers.js)
! 113: ---------------------------------
! 114:
! 115: Methods on KupuObject (kupueditor.js)
! 116: -------------------------------------
! 117:
! 118: registerTool(id, tool)
! 119: - register a tool
! 120:
! 121: getTool(id)
! 122: - return a previously registered tool
! 123:
! 124: registerFilter(filter)
! 125: - register a ContentFilter
! 126:
! 127: updateState(event)
! 128: - trigger the updateState machinery
! 129:
! 130: saveDocument()
! 131: - save the document
! 132:
! 133: prepareForm(form[, fieldid)
! 134: - add a hidden field to form with the id fieldid (defaults
! 135: to 'kupu'), should be called before the form is subbmited
! 136: to make the Kupu content get sent to the server using POST.
! 137:
! 138: execCommand(command[, param])
! 139: - perform an execCommand on the editor iframe
! 140:
! 141: getSelectedNode()
! 142: - returns the currently selected node
! 143:
! 144: getNearestParentOfType(node, type)
! 145: - returns the nearest parent of node (or node itself) of
! 146: element type
! 147:
! 148: getDocument()
! 149: - returns the document object
! 150:
! 151: getInnerDocument()
! 152: - returns the iframe.contentWindow.document
! 153:
! 154: insertNodeAtSelection(node)
! 155: - insert a new node on the cursor location
! 156:
! 157: logMessage(message, severity)
! 158: - log a message with the logger, message is the message to log and
! 159: severity is an integer that can be 0 (default) for debug messages,
! 160: 1 for warnings and 2 for errors (different loggers can be plugged
! 161: into Kupu, but a severity of 2 will usually make the logger raise
! 162: an exception).
! 163:
! 164: getBrowserName()
! 165: - return the name of the client browser, will return IE, Mozilla
! 166: or raise an exception if the client uses a non-supported one.
! 167:
! 168: getXMLBody(transform)
! 169: - transform is a Sarissa node.
! 170: Returns the body tag (or body tags if more than one) as text.
! 171:
! 172: getHTMLBody()
! 173: - returns the body node as text (including <body> tag). Will return all
! 174: body nodes if there are multiple bodies.
! 175:
! 176: setHTMLBody(text)
! 177: - sets the contents of the body to the specified HTML text
! 178: (which should not include a body tag). If there are multiple
! 179: bodies they are all replaced.
! 180:
! 181: Methods on tools (kupubasetools.js)
! 182: -----------------------------------
! 183:
! 184: KupuTool - the baseclass for tools
! 185:
! 186: initialize(editor)
! 187: - initialize the tool
! 188:
! 189: updateState(selectedNode, event)
! 190: - update the state of the tool if required
! 191:
! 192: registerToolBox(id, toolbox)
! 193: - register a ui object (ToolBox)
! 194:
! 195: KupuToolBox - the baseclass for toolboxes (view elements of tools)
! 196:
! 197: initialize(tool, editor)
! 198: - initialize the toolbox
! 199:
! 200: updateState(selNode, event)
! 201: - update the state of the UI according to the iframe's state
! 202:
! 203: Tool implementations (depending on the complexity of the tool a tool either
! 204: exists of a single Tool class, or of a Tool and a ToolBox class, the
! 205: ToolBox classes will only harbour event handlers and such so will
! 206: therefore not be documented):
! 207:
! 208: KupuUI - the toolbar, only contains event handlers and generic button
! 209: handlers
! 210:
! 211: basicButtonHandler(action)
! 212: - handle a basic action like Bold or Italic
! 213:
! 214: saveButtonHandler()
! 215:
! 216: saveAndExitButtonHandler()
! 217:
! 218: cutButtonHandler()
! 219:
! 220: copyButtonHandler()
! 221:
! 222: pasteButtonHandler()
! 223: - basic button handlers for a specific action
! 224:
! 225: setTextStyle(style)
! 226: - set the style of the current text block
! 227:
! 228: ColorchooserTool - the color picker (part of the toolbar)
! 229:
! 230: openFgColorChooser()
! 231: - open the colorchooser to pick a foreground color
! 232:
! 233: openHlColorChooser()
! 234: - open the colorchooser to pick a background color
! 235:
! 236: chooseColor()
! 237: - event handler for a click inside the colorchooser
! 238:
! 239: show()
! 240: - show the colorchooser
! 241:
! 242: hide()
! 243: - hide the colorchooser
! 244:
! 245: createColorChooser(table)
! 246: - create the colorchooser and inside the table
! 247:
! 248: PropertyTool - set the title and metadata of a document
! 249:
! 250: updateProperties()
! 251: - set the properties on the document from the form data
! 252:
! 253: LinkTool - add and edit hyperlinks
! 254:
! 255: createLink(url, type, name, target, title)
! 256: - create a link around the current selection
! 257:
! 258: deleteLink()
! 259: - delete the current link, if any
! 260:
! 261: ImageTool - add and edit images
! 262:
! 263: createImage(url, alttext, imgclass)
! 264: - create an image
! 265:
! 266: setImageClass(imgclass)
! 267: - set the class of the selected image
! 268:
! 269: TableTool - add and edit tables
! 270:
! 271: addPlainTable()
! 272: - add a table with default settings
! 273:
! 274: createTable(rows, cols, makeHeader, tableclass)
! 275: - create a table
! 276:
! 277: addTableRow()
! 278: - add a row underneath the current selected one
! 279:
! 280: delTableRow()
! 281: - delete the current table row
! 282:
! 283: addTableColumn()
! 284: - add a column to the right of the current one
! 285:
! 286: delTableColumn()
! 287: - delete the current table column
! 288:
! 289: setColumnAlign()
! 290: - set the alignment of the current column according to the form
! 291: data
! 292:
! 293: setTableClass()
! 294: - set the table class according to the form data
! 295:
! 296: ListTool - manage lists (part of the toolbar)
! 297:
! 298: addUnorderedList()
! 299: - add an unordered list
! 300:
! 301: addOrderedList()
! 302: - add an ordered list
! 303:
! 304: setUnorderedListStyle()
! 305: - set the style of the nearest unordered list parent according to
! 306: the form data
! 307:
! 308: setOrderedListStyle()
! 309: - set the style of the nearest ordered list parent according to
! 310: the form data
! 311:
! 312: ShowPathTool - show the path to the current node in the status bar
! 313:
! 314: no methods besides updateState()
! 315:
! 316: Additional helper functions, objects and methods:
! 317: -------------------------------------------------
! 318:
! 319: addEventHandler(element, event, method, context)
! 320: - bind <method> to <event> on <element>, using <context> as context
! 321: ('this' inside the method body).
! 322:
! 323: removeEventHandler(element, event, method)
! 324: - remove binding of <method> for <event> from <element>
! 325:
! 326: selectSelectItem(select, item)
! 327: - select item <item> from HTML optionlist <select>
! 328:
! 329: loadDictFromXML(document, islandid)
! 330: - load configuration values from an XML chunk
! 331:
! 332: Logger objects:
! 333:
! 334: When the KupuEditor gets initialized, it expects a logging
! 335: object with one method (log(message, severity)) to be passed
! 336: along as an argument. Two loggers are defined: 1 called
! 337: DebugLogger that will alert all messages and 1 called
! 338: PlainLogger that should be instantiated with the ids of the
! 339: element in which debug messages will be shown and the maximum
! 340: number of messages as arguments, that will show all debug
! 341: messages and warnings to the debug window and will raise an
! 342: exception for all errors.
! 343:
! 344: ContextFixer:
! 345:
! 346: A helper class to fix the contexts in methods when called in a
! 347: specific way (usually when used as an event handler). In some
! 348: cases the 'this' variable inside functions can change, this
! 349: class helps in resetting it to the object on which the method
! 350: is defined (and actually it can help in setting a different
! 351: context as well, although this will not generally be
! 352: advised). For more information see the source.
! 353:
! 354: Timer:
! 355:
! 356: A herlper class to overcome a problem with
! 357: window.setTimeout(), this has the problems that it isn't
! 358: usable to call object methods without very nasty complications
! 359: and that it doesn't allow usage of variable references as
! 360: arguments (both because the argument that is executed is a
! 361: string that will be evalled in global context). For more
! 362: information see the source.
! 363:
! 364: Array.prototype.contains(element):
! 365:
! 366: - a helper method added to the prototype of Array that will
! 367: return true if element is in the array, false if it isn't.
! 368:
! 369: String.prototype.strip(string):
! 370:
! 371: - a helper method added to the prototype of String that strips
! 372: all outer whitespace. The original string is not affected; a
! 373: new instance of String is returned.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/cvs/cvsweb/icons/back.gif){kind=icon}
Return to JSAPI.txt CVS log ![[TXT]](/cvs/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvs/cvsweb/icons/dir.gif){kind=icon}
Up to [Repository] / kupu / doc