Annotation of kupu/doc/CUSTOMIZING.txt, revision 1.1
1.1 ! dwinter 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! ;).
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/cvs/cvsweb/icons/back.gif){kind=icon}
Return to CUSTOMIZING.txt CVS log ![[TXT]](/cvs/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvs/cvsweb/icons/dir.gif){kind=icon}
Up to [Repository] / kupu / doc