[Sommaire] [Imprimer]

   1  ================
   2  Customizing Kupu
   3  ================
   4  
   5  XXX - cover customizing a feature (templating system)
   6  
   7  Abstract
   8  --------
   9  
  10  This is a document describing in detail how to customize Kupu on
  11  different levels: using CSS and HTML to change or remove parts of the
  12  UI, overriding initKupu() to reduce or extend the amount of tools used
  13  and hook in custom tools, writing tools and overriding default Kupu
  14  behaviour.
  15  
  16  Sidenote: in the Kupu package there's a subdirectory called 'silva'
  17  which contains the customizing code used for a Zope based CMS (well,
  18  not strictly but anyway ;) called 'Silva'. This code uses all the
  19  customization techniques described below, and can serve as an example
  20  for how to perform heavy customizations.
  21  
  22  Integration and customization
  23  -----------------------------
  24  
  25  Kupu is a feature-rich WYSIWYG editor and will provide a lot of
  26  ready-to-use features out-of-the-box. When one takes the default
  27  generated file kupu.html one doesn't have to change anything to use
  28  those features, but in a real-life situation, where issues like the
  29  available amount of real-estate, the capabilites of the back-end or
  30  even the expected knowledge of the users can play important roles,
  31  integrators will most likely want to perform some customization. The
  32  Kupu developers have tried to make customization clean and clear, and
  33  to provide different ways of doing customization, either changing the
  34  HTML or CSS for small customization (we understand most people
  35  deploying a tool like Kupu will usually not want to hack JavaScript,
  36  so in most cases customizing Kupu should not involve any programming)
  37  or overriding core Kupu functionality using JavaScript.
  38  
  39  Configuration
  40  -------------
  41  
  42  Even though it really doesn't belong in this document, we would like
  43  to mention configuration options as well, since they can be really
  44  useful for people who want to perform customizations, and we don't
  45  want to overlook them, ending up doing things from JavaScript that can
  46  easily be changed in the configuration... ;) Unless special features
  47  are included, Kupu has a very limited set of configuration options,
  48  which can all be set through inline XML 'islands' within the document
  49  containing Kupu.
  50  
  51  ===================== ================================================
  52  Directive             Possible values
  53  ===================== ================================================
  54  src                   the source URL of the document
  55  dst                   the URL to PUT to (not used for POST setups)
  56  use_css               whether Kupu should try to (it will succeed in
  57                        Mozilla use CSS for bold, italic etc. rather
  58                        then plain <b>, <i> or <strong>, <em> tags
  59  reload_after_save     whether Kupu should reload the iframe's content
  60                        after saving, or keep it in tact, retaining
  61                        cursor position, selection etc. (the last is
  62                        obviously the nicest)
  63  
  64  strict_output         when set to 1, Kupu will send a full XHTML
  65                        compliant document, including document type
  66                        declaration and xmlns namespace declaration to
  67                        the server
  68  ===================== ================================================
  69    
  70  CSS customization
  71  -----------------
  72  
  73  If an integrator wants to customize small issues, like the image of a
  74  toolbar button, the font of a toolbox but also whether a toolbox or a
  75  button should appear in the client's page, he can modify the
  76  CSS. There's one main CSS, kupustyles.css, which contains classnames
  77  or ids for each button and toolbar. To change a color, image or font
  78  of that element, just override the CSS for the class or id that points
  79  to that element (note that classes are sometimes chosen where ids seem
  80  more appropriate, this is because one can do more with CSS classes
  81  from JavaScript: when dynamically changing an id of an element, any
  82  CSS directives connected to that id will not be performed, when doing
  83  so with a class instead the CSS directives *will* be performed),
  84  perferrably in another CSS file (having a seperate CSS file for
  85  overriding CSS will improve maintainability: when you upgrade from an
  86  already customized Kupu to a newer version you don't have to modify
  87  the core's CSS).
  88  
  89  To remove an element from the page easily, you can add 'display: none'
  90  as a style directive for the element, it will be hidden from
  91  view. Note that it is also possible to remove the complete tool from
  92  the view using JavaScript, which has the advantage that less data has
  93  to be sent to the client and the HTML will become a bit smaller, but
  94  is a bit harder.
  95    
  96  Changing initKupu
  97  -----------------
  98  
  99  In one of the JavaScript files, kupuinit.js, there's a function called
 100  initKupu(). Here's where the bootstrapping takes place: the editor is
 101  instantiated and configuration and a logger are fed to it, the
 102  contextmenu and the tools are instantiated and registered etc. If you
 103  want to override or completely remove tools and context menu etc. from
 104  Kupu, you will need to override (probably copy and change) this
 105  function.  When you want to remove a tool from Kupu, remove the lines
 106  in which it is instantiated and registered from your custom
 107  initKupu. When you subclass an existing tool or want to plug in your
 108  own, copy the lines of code used to instantiate an existing tool and
 109  change them.  Since Kupu is still in development (even thought we
 110  passed 1.0 a while ago, unfortunatly it showed things aren't
 111  completely the way they should be, hopefully at some point the API and
 112  core will be frozen for a while) you can expect customized initKupu's
 113  need modification after an Kupu upgrade. For instance, in 1.0.1 a
 114  toolbox was reflected by 1 JavaScript class, nowadays there's a
 115  seperate class for the functionality of that tool and one for the UI
 116  elements. The initKupu functions that are written for 1.0.1 need to be
 117  modified to reflect this change. If you override this function, before
 118  starting an upgrade be sure to check out the documentation or the
 119  mailinglist, where changes that break customized initKupu functions
 120  will be mentioned.
 121  
 122  Removing or changing tools
 123  --------------------------
 124  
 125  As mentioned in the previous paragraph, to remove a tool from Kupu
 126  completely you can just remove the lines in which it (and it's UI
 127  element) is instantiated. However, in some cases you will want to use
 128  or re-use the functionality of the tool class and get rid of or
 129  override the UI element.  If you don't want the UI toolbox element of
 130  the TableTool to be part of the HTML, but *do* want the contextmenu's
 131  table functionality available (which is also provided via the tools),
 132  the UI element shouldn't be visible but the tool itself should be
 133  available. This case could be solved using CSS (display: none) but if
 134  you have an overridden initKupu anyway, or if you really appreciate
 135  clean HTML it can be done using initKupu as well, by just not
 136  registering the UI element (TableToolBox) to the tool (TableTool).
 137  When you want to change the UI part of a tool, or want to override
 138  such a toolbox you can just register it to the tool in a similar way.
 139  
 140  The KupuTool and KupuToolBox APIs
 141  ---------------------------------
 142  
 143  For a reference of the KupuTool and KupuToolBox API's, see
 144  JSAPI.txt. For a description of how to write them, see EXTENDING.txt.
 145  
 146  Overriding KupuEditor methods
 147  -----------------------------
 148  
 149  To override methods on the KupuEditor object, you can either attach a
 150  method with the name of the one to override to the prototype of the
 151  class or create a subclass. We did our best to make the API available
 152  on this core object clean and small, and to keep the methods single
 153  operations as much as possible, so overriding a method on this object
 154  usually won't involve much code duplication. Note: unfortunately this
 155  is not really the case for saveDocument (although I guess the need for
 156  overriding this is a lot smaller now that prepareForm is available ;)
 157  and especially not for insertNodeAtSelection (if someone wants to
 158  rewrite that to something a bit more compact, please do! ;).