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>