Annotation of kupuMPIWG/doc/PLONE2.txt, revision 1.1.1.1
1.1 dwinter 1: =========================
2: Installing Kupu in Plone2
3: =========================
4:
5: .. contents:: Table of Contents
6: :depth: 2
7: :backlinks: top
8:
9: .. sectnum::
10: :depth: 2
11:
12: Requirements
13: ------------
14:
15: * Zope 2.7 and Python 2.3.3 or greater
16:
17: * Plone 2.0 or greater
18:
19: * CMF 1.4 or greater
20:
21: If you are installing a development build checked out from SVN then
22: you also need:
23:
24: * An XSLT processor with XInclude support, such as xsltproc from
25: Gnome's libxml/libxslt.
26:
27: You do not require an XSLT processor if you are installing a released
28: version of Kupu.
29:
30: Installation
31: ------------
32:
33: Drop the 'kupu' directory into your instance home's Products
34: directory.
35:
36: If you are installing from a release tar bundle, the following build
37: steps may be skipped. Skip down to the paragraph starting `Now restart
38: the Zope instance`_.
39:
40: If you are installing a version checked out of SVN then you must
41: generate the Plone template by typing::
42:
43: $ make plonemacros
44:
45: If you see xsltproc throw an error about not being able to load
46: external entities, ignore it.
47:
48: Windows users need to first get a copy of xsltproc.exe from
49: http://www.zlatkovic.com/pub/libxml/. As a minimum you need to
50: download the zipfiles for libxslt, libxml2, iconv and zlib.
51: Extracting all of the .dll and .exe files into ``c:\libxslt`` is
52: sufficient for the make command to work (ignore subdirectories in the
53: zipfiles). Then just start a command prompt in the kupu directory and
54: run the same command as for other users (on windows it runs make.bat
55: so you don't need a separate make program)::
56:
57: C:\>cd \Plone 2\Data\Products\kupu
58: C:\Plone 2\Data\Products\kupu>make plonemacros
59:
60: .. _Now restart the Zope instance:
61:
62: Now restart the Zope instance. Now go to the Plone Control Panel,
63: section Add/remove Products and select 'kupu' for installation.
64:
65: Usually, every user has to explicitly set their preferred editor to
66: 'kupu' in 'My Preferences' in order to use kupu. Kupu and recent
67: versions of Epoz may both be installed on the same Plone site allowing
68: users to choose whichever they prefer. You can specify Kupu as the
69: default editor for new users from the ZMI::
70:
71: "portal_memberdata" -> "Properties" -> "wysiwyg_editor" = "Kupu"
72:
73: Upgrading
74: =========
75: If you are upgrading from an earlier version of Kupu then be aware
76: that some of the default settings for Plone may have changed.
77:
78: If you have not changed any of the default settings, then you should
79: run the new 'sample-kupu-customisation-policy' script in the
80: kupu-plone skin folder. This will reset all configuration options to
81: their defaults.
82:
83: If you have customised your own setting then you should create your
84: own 'kupu-customisation-policy' script based on the sample. The script
85: has been written such that in most cases only the data declarations at
86: the beginning of the script will need changing.
87:
88: Installation Problems
89: =====================
90:
91: Macro Nesting
92: ~~~~~~~~~~~~~
93:
94: When attempting to use Kupu, if you see the message::
95:
96: Kupu not installed correctly: macro nesting limit (100) exceeded ...
97:
98: it probably means that the ``make`` command was not run, or failed to
99: run for some reason.
100:
101: Zoom
102: ~~~~
103:
104: If zooming the Kupu window leaves parts of the underlying page still
105: visible it is possible that some part of the page is specifying an
106: explicit z-index. Try customising kupustyles.css and increasing the
107: setting for z-index in::
108:
109: div.kupu-fulleditor-zoomed {
110: z-index: 1;
111: margin: 0; border: none;
112: position: fixed;
113: top: 0; left: 0;
114: }
115:
116:
117: This function requires better XML support in your browser.
118: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119:
120: You can get this alert in Firefox and Mozilla if your Plone site has
121: an incompatible copy of Sarissa installed. Check your Plone skin
122: folders to see if there is a second copy of sarissa.js present and
123: if so ensure that the kupu skin folders are higher priority.
124:
125: Plone Configlet
126: ---------------
127:
128: When logged in as a Manager use the 'Plone Setup' to get to the Plone
129: control panel. Kupu appears as a configurable product on the control
130: panel.
131:
132: You can also define a customisation policy script called
133: `kupu-customisation-policy` in a skin folder. If there is a script of
134: this name then it will be run automatically every time you install (or
135: reinstall) kupu in your plone site. This script should use the
136: kupu_library_tool to set up the configuration as you wish it for your
137: site.
138:
139: Creating a customisation policy script is optional, but is a simple
140: way to ensure that you do not lose customised configuration settings
141: when upgrading. A sample script is in the kupu_plone_layer folder.
142:
143: config tab
144: ==========
145:
146: .. contents:: config tab
147: :depth: 1
148: :local:
149: :backlinks: top
150:
151: Link options
152: ~~~~~~~~~~~~
153: When this is checked:
154:
155: - If you insert an image, or create an internal link to an Archetypes
156: object, then the link will indirect through Archetypes catalog. This
157: means that you can move the target object to a different location, or
158: even rename it, and the link will continue to work.
159:
160: - the URL used for the link will require an extra hit on the server,
161: and will contain the internal UID. These issues may be avoided by
162: configuring the output transform for image caption support (`see
163: below`__).
164:
165: __ captioning_
166:
167: - Links to non-Archetypes objects are not affected by this option.
168:
169: When this is not checked:
170:
171: - Links to all objects simply link to the current URL of the object.
172:
173: Warn before losing changes
174: ~~~~~~~~~~~~~~~~~~~~~~~~~~
175:
176: When this is checked:
177:
178: - Kupu installs its own support to detect changes to any form
179: containing Kupu. It will warn before leaving the page if any
180: controls appear to have changed.
181:
182: When this is not checked:
183:
184: - Kupu does not install its own code, but it will use the code if it
185: installed by anything else. For example, if your copy of Plone
186: includes the support by default for all main forms Kupu you might
187: turn this option off and Kupu would continue to work with the
188: default code.
189:
190: Styles
191: ~~~~~~
192:
193: Tables
194: ::::::
195: Enter a list of styles to be used for tables. The classname in the CSS
196: must exactly match the style displayed in the table style pulldown.
197:
198: The default list of table styles is ``plain``, ``listing``, ``grid``,
199: ``data``. Only ``listing`` is defined in the default Plone css, you
200: should add suitable rules for the other styles to ``ploneCustom.css``.
201:
202: Paragraph Styles
203: ::::::::::::::::
204: Enter a list of styles to be added to the style pulldown. See `Custom
205: Paragraph Styles`_.
206:
207:
208: HTML Filter
209: ~~~~~~~~~~~
210:
211: Tags & Attributes
212: :::::::::::::::::
213:
214: This section lists combinations of tags and attributes which are
215: stripped out of documents when they are being saved. By default all
216: combinations of tags and attributes which are defined for
217: xhtml-transitional are permitted (except for the event attributes such
218: as ``onload``). Any other combination of tags and attributes will be
219: removed.
220:
221: You may further restrict the permitted combination of tags and
222: attributes by entering a combination to be blacklisted in the two
223: textareas. If you leave the tag box blank then any attributes listed
224: are blacklisted for all tags. If you leave the attribute box blank,
225: then any tags entered are removed entirely. If you enter both tags and
226: attributes then the attributes are removed when they occur on those
227: specific tags.
228:
229: To delete a filter rule remove the checkmark next to any existing line
230: of tags and attributes, then save the form.
231:
232: Style Whitelist
233: :::::::::::::::
234:
235: CSS style elements may be embedded in the style attribute, but by
236: default these are all removed by filtering. Add any style elements you
237: wish to have preserved to the style whitelist.
238:
239: The styles ``text-align`` and ``list-style-type`` are set by Kupu, so
240: if you remove them from the whitelist you should also hide the
241: relevant toolbar buttons to prevent users setting styles which are
242: lost on saving.
243:
244: Class Blacklist
245: :::::::::::::::
246:
247: This box contains a list of CSS classnames which are to be stripped
248: when a document is saved. You could, for example, fill the list with
249: all the styles commonly used in Microsoft Word documents (MsoNormal
250: etc.) to cleanup text pasted from Word.
251:
252:
253: libraries tab
254: =============
255:
256: This form supplies the list of libraries which form the leftmost
257: column of the image and internal link drawers.
258:
259: resource types tab
260: ==================
261:
262: While libraries provide abstract locations for objects of any type,
263: Kupu distinguishes objects by resource type. For example, a user might
264: request a library showing objects to link to or a library showing
265: objects to be inserted into a document. The abstract location
266: (library) might be the same, but the former library would contain
267: documents, the latter images.
268:
269: This management screen allows you to define resource types using a
270: list of portal types.
271:
272: linkable
273: This entry lists all of the content types which are
274: available in the internal link drawer.
275:
276: mediaobject
277: This entry lists all of the content types which are available
278: in the image drawer.
279:
280: collection
281: This entry lists all the folder types which may be used when
282: navigating in the drawers. collection types may be navigated
283: but not selected.
284:
285: documentation tab
286: =================
287:
288: This tab will display the file you are reading. If your Plone system
289: has Portal Transforms and docutils installed the file will be
290: formatted, otherwise it displays the reStructuredText source of the
291: file.
292:
293: Custom Paragraph styles
294: -----------------------
295: Paragraph styles come from 3 sources:
296:
297: a) The style ``Normal`` is always defined
298:
299: b) Use the Plone control panel to add additional styles to be
300: available on all content types. ``Heading``, ``Subheading`` and
301: ``Formatted`` are added automatically on installation.
302:
303: c) For Archetypes content types additional styles may be defined for
304: individual fields.
305:
306: Styles defined under `Paragraph Styles`_ in the control panel are in the format ``title|tag``
307: or ``title|tag|class``. e.g.::
308:
309: Heading|h2
310: Subheading|h3
311: Formatted|pre
312: Pull Quote|div|pullQuote
313:
314: Each rich text field can define its own set of paragraph styles to be
315: made available in kupu. These are defined on the ``parastyles`` attribute
316: of the ``RichWidget``. For example, a typical field definition might be::
317:
318: TextField('bodyCopy',
319: allowable_content_types=('text/html',),
320: default_output_type='text/x-html-captioned', # see below
321: required=1,
322: searchable=1,
323: widget=RichWidget
324: (description='Please paste or type your article here',
325: label='Body Copy',
326: parastyles=(
327: ('div|pullQuote','Pull Quote'),
328: ('div|Caption','Caption'),
329: ('div|contactInformation','Contact Information'),
330: ('div|notesToEditors','Notes to editors'),
331: ),
332: ),
333: ),
334:
335: ``parastyles`` is a sequence of style definitions. Each definition should
336: be a 2-tuple of strings. The first string if either the tag to be
337: added, or tag, vertical bar, class to be assigned to the tag. The
338: second string is the caption that appears in the style pulldown.
339:
340: Images
341: ------
342:
343: The image drawer contains radio buttons to select left, inline or
344: right alignment on pasted images. For this to work your CSS must
345: define classes ``image-left``, ``image-inline`` and ``image-right``. You
346: should add these as in the example below even if you do not require
347: the optional captioning support.
348:
349: .. _captioning:
350:
351: Optionally kupu can automatically add captions to images. To enable
352: this feature you must be linking to an Archetypes based image type,
353: and the field you are editing must have its ``default_output_type`` set to
354: ``text/x-html-captioned`` in the Archetypes schema. If both of these
355: conditions are filled, then the image drawer will include a checkbox
356: for captioning an image. By default this is checked, turn it off to
357: disable the caption on that image.
358:
359: The caption is added when the page is viewed. All img tags for
360: captioned images are replaced by an img tag in nested divs. The class
361: for the img tag is moved to the enclosing div, and the current image
362: description is appended in a div with class ``image-caption``. If the
363: original image was in a div or paragraph by itself then the enclosing
364: tag is also removed. In other words::
365:
366: <img class="image-left captioned" width="200" ... />
367:
368: is replaced by::
369:
370: <div class="image-left captioned" style="width:200px;">
371: <div><img width="200" ... /></div>
372: <div class="image-caption">
373: ...description text...
374: </div>
375: </div>
376:
377: You need to add some styles to your ``ploneCustom.css``. At the least, you
378: should set ``div.image-caption`` appropriately, you probably also want to
379: set classes for displaying images floated left, inline or right::
380:
381: div.image-caption {
382: background: #e0e0e0;
383: border: 0 none black;
384: overflow: hidden;
385: }
386: .image-left {
387: float: left;
388: clear: both;
389: }
390: .image-inline {
391: float: none;
392: }
393: .image-right {
394: float: right;
395: clear: both;
396: }
397:
398: References from HTML text
399: -------------------------
400: Kupu can be made to store archetypes references for any HTML field.
401: You can use these references for a variety of purposes, e.g. when
402: publishing a document you could automatically publish all the
403: contained images.
404:
405: To enable this feature for a particular field, you need to change the
406: type of the field from ``TextField`` to ``ReftextField``::
407:
408: from Products.kupu.plone.ReftextField import ReftextField
409:
410: then define your field as::
411:
412: Reftextfield('bodyCopy',
413: required=1,
414: searchable=1,
415: relationship='bodyCopy',
416: widget=RichWidget
417: (description='Please paste or type your article here',
418: label='Body Copy',
419: parastyles=(
420: ('div|pullQuote','Pull Quote'),
421: ('div|Caption','Caption'),
422: ('div|contactInformation','Contact Information'),
423: ('div|notesToEditors','Notes to editors'),
424: ),
425: ),
426: ),
427:
428: the ``ReftextField`` type is identical to the existing ``TextField``
429: except that it also extracts references from the HTML text whenever
430: the field is saved. The relationship used to hold the references may
431: be specified as shown, but if omitted it defaults to the field name.
432:
433: If the HTML contains an invalid reference, e.g. a link to an object
434: that has since been deleted, ``ReftextField`` will completely ignore
435: that link.
436:
437: Migrating from Epoz
438: -------------------
439:
440: Epoz and Kupu will coexist: simply install both products. If you are
441: running an old version of Epoz you should either upgrade to a more
442: recent version, or ensure that the Kupu skin folders are searched
443: before the Epoz ones. Then encourage all your users to select Kupu as
444: their default editor from their user preferences.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/cvs/cvsweb/icons/back.gif){kind=icon}
Return to PLONE2.txt CVS log ![[TXT]](/cvs/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvs/cvsweb/icons/dir.gif){kind=icon}
Up to [Repository] / kupuMPIWG / doc