159 lines
7.8 KiB
Plaintext
159 lines
7.8 KiB
Plaintext
================
|
|
Customizing Kupu
|
|
================
|
|
|
|
XXX - cover customizing a feature (templating system)
|
|
|
|
Abstract
|
|
--------
|
|
|
|
This is a document describing in detail how to customize Kupu on
|
|
different levels: using CSS and HTML to change or remove parts of the
|
|
UI, overriding initKupu() to reduce or extend the amount of tools used
|
|
and hook in custom tools, writing tools and overriding default Kupu
|
|
behaviour.
|
|
|
|
Sidenote: in the Kupu package there's a subdirectory called 'silva'
|
|
which contains the customizing code used for a Zope based CMS (well,
|
|
not strictly but anyway ;) called 'Silva'. This code uses all the
|
|
customization techniques described below, and can serve as an example
|
|
for how to perform heavy customizations.
|
|
|
|
Integration and customization
|
|
-----------------------------
|
|
|
|
Kupu is a feature-rich WYSIWYG editor and will provide a lot of
|
|
ready-to-use features out-of-the-box. When one takes the default
|
|
generated file kupu.html one doesn't have to change anything to use
|
|
those features, but in a real-life situation, where issues like the
|
|
available amount of real-estate, the capabilites of the back-end or
|
|
even the expected knowledge of the users can play important roles,
|
|
integrators will most likely want to perform some customization. The
|
|
Kupu developers have tried to make customization clean and clear, and
|
|
to provide different ways of doing customization, either changing the
|
|
HTML or CSS for small customization (we understand most people
|
|
deploying a tool like Kupu will usually not want to hack JavaScript,
|
|
so in most cases customizing Kupu should not involve any programming)
|
|
or overriding core Kupu functionality using JavaScript.
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
Even though it really doesn't belong in this document, we would like
|
|
to mention configuration options as well, since they can be really
|
|
useful for people who want to perform customizations, and we don't
|
|
want to overlook them, ending up doing things from JavaScript that can
|
|
easily be changed in the configuration... ;) Unless special features
|
|
are included, Kupu has a very limited set of configuration options,
|
|
which can all be set through inline XML 'islands' within the document
|
|
containing Kupu.
|
|
|
|
===================== ================================================
|
|
Directive Possible values
|
|
===================== ================================================
|
|
src the source URL of the document
|
|
dst the URL to PUT to (not used for POST setups)
|
|
use_css whether Kupu should try to (it will succeed in
|
|
Mozilla use CSS for bold, italic etc. rather
|
|
then plain <b>, <i> or <strong>, <em> tags
|
|
reload_after_save whether Kupu should reload the iframe's content
|
|
after saving, or keep it in tact, retaining
|
|
cursor position, selection etc. (the last is
|
|
obviously the nicest)
|
|
|
|
strict_output when set to 1, Kupu will send a full XHTML
|
|
compliant document, including document type
|
|
declaration and xmlns namespace declaration to
|
|
the server
|
|
===================== ================================================
|
|
|
|
CSS customization
|
|
-----------------
|
|
|
|
If an integrator wants to customize small issues, like the image of a
|
|
toolbar button, the font of a toolbox but also whether a toolbox or a
|
|
button should appear in the client's page, he can modify the
|
|
CSS. There's one main CSS, kupustyles.css, which contains classnames
|
|
or ids for each button and toolbar. To change a color, image or font
|
|
of that element, just override the CSS for the class or id that points
|
|
to that element (note that classes are sometimes chosen where ids seem
|
|
more appropriate, this is because one can do more with CSS classes
|
|
from JavaScript: when dynamically changing an id of an element, any
|
|
CSS directives connected to that id will not be performed, when doing
|
|
so with a class instead the CSS directives *will* be performed),
|
|
perferrably in another CSS file (having a seperate CSS file for
|
|
overriding CSS will improve maintainability: when you upgrade from an
|
|
already customized Kupu to a newer version you don't have to modify
|
|
the core's CSS).
|
|
|
|
To remove an element from the page easily, you can add 'display: none'
|
|
as a style directive for the element, it will be hidden from
|
|
view. Note that it is also possible to remove the complete tool from
|
|
the view using JavaScript, which has the advantage that less data has
|
|
to be sent to the client and the HTML will become a bit smaller, but
|
|
is a bit harder.
|
|
|
|
Changing initKupu
|
|
-----------------
|
|
|
|
In one of the JavaScript files, kupuinit.js, there's a function called
|
|
initKupu(). Here's where the bootstrapping takes place: the editor is
|
|
instantiated and configuration and a logger are fed to it, the
|
|
contextmenu and the tools are instantiated and registered etc. If you
|
|
want to override or completely remove tools and context menu etc. from
|
|
Kupu, you will need to override (probably copy and change) this
|
|
function. When you want to remove a tool from Kupu, remove the lines
|
|
in which it is instantiated and registered from your custom
|
|
initKupu. When you subclass an existing tool or want to plug in your
|
|
own, copy the lines of code used to instantiate an existing tool and
|
|
change them. Since Kupu is still in development (even thought we
|
|
passed 1.0 a while ago, unfortunatly it showed things aren't
|
|
completely the way they should be, hopefully at some point the API and
|
|
core will be frozen for a while) you can expect customized initKupu's
|
|
need modification after an Kupu upgrade. For instance, in 1.0.1 a
|
|
toolbox was reflected by 1 JavaScript class, nowadays there's a
|
|
seperate class for the functionality of that tool and one for the UI
|
|
elements. The initKupu functions that are written for 1.0.1 need to be
|
|
modified to reflect this change. If you override this function, before
|
|
starting an upgrade be sure to check out the documentation or the
|
|
mailinglist, where changes that break customized initKupu functions
|
|
will be mentioned.
|
|
|
|
Removing or changing tools
|
|
--------------------------
|
|
|
|
As mentioned in the previous paragraph, to remove a tool from Kupu
|
|
completely you can just remove the lines in which it (and it's UI
|
|
element) is instantiated. However, in some cases you will want to use
|
|
or re-use the functionality of the tool class and get rid of or
|
|
override the UI element. If you don't want the UI toolbox element of
|
|
the TableTool to be part of the HTML, but *do* want the contextmenu's
|
|
table functionality available (which is also provided via the tools),
|
|
the UI element shouldn't be visible but the tool itself should be
|
|
available. This case could be solved using CSS (display: none) but if
|
|
you have an overridden initKupu anyway, or if you really appreciate
|
|
clean HTML it can be done using initKupu as well, by just not
|
|
registering the UI element (TableToolBox) to the tool (TableTool).
|
|
When you want to change the UI part of a tool, or want to override
|
|
such a toolbox you can just register it to the tool in a similar way.
|
|
|
|
The KupuTool and KupuToolBox APIs
|
|
---------------------------------
|
|
|
|
For a reference of the KupuTool and KupuToolBox API's, see
|
|
JSAPI.txt. For a description of how to write them, see EXTENDING.txt.
|
|
|
|
Overriding KupuEditor methods
|
|
-----------------------------
|
|
|
|
To override methods on the KupuEditor object, you can either attach a
|
|
method with the name of the one to override to the prototype of the
|
|
class or create a subclass. We did our best to make the API available
|
|
on this core object clean and small, and to keep the methods single
|
|
operations as much as possible, so overriding a method on this object
|
|
usually won't involve much code duplication. Note: unfortunately this
|
|
is not really the case for saveDocument (although I guess the need for
|
|
overriding this is a lot smaller now that prepareForm is available ;)
|
|
and especially not for insertNodeAtSelection (if someone wants to
|
|
rewrite that to something a bit more compact, please do! ;).
|