[Sommaire] [Imprimer]

   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.