Annotation of kupuMPIWG/doc/JSAPI.txt, revision 1.1.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] / kupuMPIWG / doc