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