Annotation of kupu/doc/CUSTOMIZING.txt, revision 1.1.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