Return to PLONE2.txt CVS log

Up to [Repository] / kupuMPIWG / doc

=========================
Installing Kupu in Plone2
=========================

.. contents:: Table of Contents
   :depth: 2
   :backlinks: top

.. sectnum::
   :depth: 2

Requirements
------------

* Zope 2.7 and Python 2.3.3 or greater

* Plone 2.0 or greater

* CMF 1.4 or greater

If you are installing a development build checked out from SVN then
you also need:

* An XSLT processor with XInclude support, such as xsltproc from
  Gnome's libxml/libxslt.

You do not require an XSLT processor if you are installing a released
version of Kupu.

Installation
------------

Drop the 'kupu' directory into your instance home's Products
directory.

If you are installing from a release tar bundle, the following build
steps may be skipped. Skip down to the paragraph starting `Now restart
the Zope instance`_.

If you are installing a version checked out of SVN then you must
generate the Plone template by typing::

  $ make plonemacros

If you see xsltproc throw an error about not being able to load
external entities, ignore it.

Windows users need to first get a copy of xsltproc.exe from
http://www.zlatkovic.com/pub/libxml/. As a minimum you need to
download the zipfiles for libxslt, libxml2, iconv and zlib.
Extracting all of the .dll and .exe files into ``c:\libxslt`` is
sufficient for the make command to work (ignore subdirectories in the
zipfiles). Then just start a command prompt in the kupu directory and
run the same command as for other users (on windows it runs make.bat
so you don't need a separate make program)::

   C:\>cd \Plone 2\Data\Products\kupu
   C:\Plone 2\Data\Products\kupu>make plonemacros

.. _Now restart the Zope instance:

Now restart the Zope instance. Now go to the Plone Control Panel,
section Add/remove Products and select 'kupu' for installation.

Usually, every user has to explicitly set their preferred editor to
'kupu' in 'My Preferences' in order to use kupu. Kupu and recent
versions of Epoz may both be installed on the same Plone site allowing
users to choose whichever they prefer. You can specify Kupu as the
default editor for new users from the ZMI::

  "portal_memberdata" -> "Properties" -> "wysiwyg_editor" = "Kupu"

Upgrading
=========
If you are upgrading from an earlier version of Kupu then be aware
that some of the default settings for Plone may have changed.

If you have not changed any of the default settings, then you should
run the new 'sample-kupu-customisation-policy' script in the
kupu-plone skin folder. This will reset all configuration options to
their defaults.

If you have customised your own setting then you should create your
own 'kupu-customisation-policy' script based on the sample. The script
has been written such that in most cases only the data declarations at
the beginning of the script will need changing.

Installation Problems
=====================

Macro Nesting
~~~~~~~~~~~~~

When attempting to use Kupu, if you see the message::

       Kupu not installed correctly: macro nesting limit (100) exceeded ...

it probably means that the ``make`` command was not run, or failed to
run for some reason.

Zoom
~~~~

If zooming the Kupu window leaves parts of the underlying page still
visible it is possible that some part of the page is specifying an
explicit z-index. Try customising kupustyles.css and increasing the
setting for z-index in::

    div.kupu-fulleditor-zoomed {
       z-index: 1;
       margin: 0; border: none;
       position: fixed;
       top: 0; left: 0;
    }


This function requires better XML support in your browser.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can get this alert in Firefox and Mozilla if your Plone site has
an incompatible copy of Sarissa installed. Check your Plone skin
folders to see if there is a second copy of sarissa.js present and
if so ensure that the kupu skin folders are higher priority.

Plone Configlet
---------------

When logged in as a Manager use the 'Plone Setup' to get to the Plone
control panel. Kupu appears as a configurable product on the control
panel.

You can also define a customisation policy script called
`kupu-customisation-policy` in a skin folder. If there is a script of
this name then it will be run automatically every time you install (or
reinstall) kupu in your plone site. This script should use the
kupu_library_tool to set up the configuration as you wish it for your
site.

Creating a customisation policy script is optional, but is a simple
way to ensure that you do not lose customised configuration settings
when upgrading. A sample script is in the kupu_plone_layer folder.

config tab
==========

.. contents:: config tab
        :depth: 1
        :local:
        :backlinks: top

Link options
~~~~~~~~~~~~
When this is checked:

 - If you insert an image, or create an internal link to an Archetypes
   object, then the link will indirect through Archetypes catalog. This
   means that you can move the target object to a different location, or
   even rename it, and the link will continue to work.

 - the URL used for the link will require an extra hit on the server,
   and will contain the internal UID. These issues may be avoided by
   configuring the output transform for image caption support (`see
   below`__).

__ captioning_

 - Links to non-Archetypes objects are not affected by this option.

When this is not checked:

 - Links to all objects simply link to the current URL of the object.

Warn before losing changes
~~~~~~~~~~~~~~~~~~~~~~~~~~

When this is checked:

 - Kupu installs its own support to detect changes to any form
   containing Kupu. It will warn before leaving the page if any
   controls appear to have changed.

When this is not checked:

 - Kupu does not install its own code, but it will use the code if it
   installed by anything else. For example, if your copy of Plone
   includes the support by default for all main forms Kupu you might
   turn this option off and Kupu would continue to work with the
   default code.

Styles
~~~~~~

Tables
::::::
Enter a list of styles to be used for tables. The classname in the CSS
must exactly match the style displayed in the table style pulldown.

The default list of table styles is ``plain``, ``listing``, ``grid``,
``data``. Only ``listing`` is defined in the default Plone css, you
should add suitable rules for the other styles to ``ploneCustom.css``.

Paragraph Styles
::::::::::::::::
Enter a list of styles to be added to the style pulldown. See `Custom
Paragraph Styles`_.


HTML Filter
~~~~~~~~~~~

Tags & Attributes
:::::::::::::::::

This section lists combinations of tags and attributes which are
stripped out of documents when they are being saved. By default all
combinations of tags and attributes which are defined for
xhtml-transitional are permitted (except for the event attributes such
as ``onload``). Any other combination of tags and attributes will be
removed.

You may further restrict the permitted combination of tags and
attributes by entering a combination to be blacklisted in the two
textareas. If you leave the tag box blank then any attributes listed
are blacklisted for all tags. If you leave the attribute box blank,
then any tags entered are removed entirely. If you enter both tags and
attributes then the attributes are removed when they occur on those
specific tags.

To delete a filter rule remove the checkmark next to any existing line
of tags and attributes, then save the form.

Style Whitelist
:::::::::::::::

CSS style elements may be embedded in the style attribute, but by
default these are all removed by filtering. Add any style elements you
wish to have preserved to the style whitelist.

The styles ``text-align`` and ``list-style-type`` are set by Kupu, so
if you remove them from the whitelist you should also hide the
relevant toolbar buttons to prevent users setting styles which are
lost on saving. 

Class Blacklist
:::::::::::::::

This box contains a list of CSS classnames which are to be stripped
when a document is saved. You could, for example, fill the list with
all the styles commonly used in Microsoft Word documents (MsoNormal
etc.) to cleanup text pasted from Word.


libraries tab
=============

This form supplies the list of libraries which form the leftmost
column of the image and internal link drawers.

resource types tab
==================

While libraries provide abstract locations for objects of any type,
Kupu distinguishes objects by resource type. For example, a user might
request a library showing objects to link to or a library showing
objects to be inserted into a document. The abstract location
(library) might be the same, but the former library would contain
documents, the latter images.

This management screen allows you to define resource types using a
list of portal types.

   linkable
       This entry lists all of the content types which are
       available in the internal link drawer.

   mediaobject
       This entry lists all of the content types which are available
       in the image drawer.

   collection
       This entry lists all the folder types which may be used when
       navigating in the drawers. collection types may be navigated
       but not selected.

documentation tab
=================

This tab will display the file you are reading. If your Plone system
has Portal Transforms and docutils installed the file will be
formatted, otherwise it displays the reStructuredText source of the
file.

Custom Paragraph styles
-----------------------
Paragraph styles come from 3 sources:

   a) The style ``Normal`` is always defined

   b) Use the Plone control panel to add additional styles to be
      available on all content types. ``Heading``, ``Subheading`` and 
      ``Formatted`` are added automatically on installation.

   c) For Archetypes content types additional styles may be defined for
      individual fields.

Styles defined under `Paragraph Styles`_ in the control panel are in the format ``title|tag``
or ``title|tag|class``. e.g.::

    Heading|h2
    Subheading|h3
    Formatted|pre
    Pull Quote|div|pullQuote

Each rich text field can define its own set of paragraph styles to be
made available in kupu. These are defined on the ``parastyles`` attribute
of the ``RichWidget``. For example, a typical field definition might be::

        TextField('bodyCopy',
            allowable_content_types=('text/html',),
            default_output_type='text/x-html-captioned', # see below
            required=1,
            searchable=1,
            widget=RichWidget
            (description='Please paste or type your article here',
                label='Body Copy',
                parastyles=(
                 ('div|pullQuote','Pull Quote'),
                 ('div|Caption','Caption'),
                 ('div|contactInformation','Contact Information'),
                 ('div|notesToEditors','Notes to editors'),
                ),
            ),
        ),

``parastyles`` is a sequence of style definitions. Each definition should
be a 2-tuple of strings. The first string if either the tag to be
added, or tag, vertical bar, class to be assigned to the tag. The
second string is the caption that appears in the style pulldown.

Images
------

The image drawer contains radio buttons to select left, inline or
right alignment on pasted images. For this to work your CSS must
define classes ``image-left``, ``image-inline`` and ``image-right``. You
should add these as in the example below even if you do not require
the optional captioning support.

.. _captioning:

Optionally kupu can automatically add captions to images. To enable
this feature you must be linking to an Archetypes based image type,
and the field you are editing must have its ``default_output_type`` set to
``text/x-html-captioned`` in the Archetypes schema. If both of these
conditions are filled, then the image drawer will include a checkbox
for captioning an image. By default this is checked, turn it off to
disable the caption on that image.

The caption is added when the page is viewed. All img tags for
captioned images are replaced by an img tag in nested divs. The class
for the img tag is moved to the enclosing div, and the current image
description is appended in a div with class ``image-caption``. If the
original image was in a div or paragraph by itself then the enclosing
tag is also removed. In other words::

    <img class="image-left captioned" width="200" ... />

is replaced by::

    <div class="image-left captioned" style="width:200px;">
      <div><img width="200" ... /></div>
      <div class="image-caption">
         ...description text...
      </div>
    </div>

You need to add some styles to your ``ploneCustom.css``. At the least, you
should set ``div.image-caption`` appropriately, you probably also want to
set classes for displaying images floated left, inline or right::

    div.image-caption {
      background: #e0e0e0;
      border: 0 none black;
      overflow: hidden;
    }
    .image-left {
       float: left;
       clear: both;
    }
    .image-inline {
       float: none;
    }
    .image-right {
       float: right;
       clear: both;
    }

References from HTML text
-------------------------
Kupu can be made to store archetypes references for any HTML field.
You can use these references for a variety of purposes, e.g. when
publishing a document you could automatically publish all the
contained images.

To enable this feature for a particular field, you need to  change the
type of the field from ``TextField`` to ``ReftextField``::

    from Products.kupu.plone.ReftextField import ReftextField

then define your field as::

        Reftextfield('bodyCopy',
            required=1,
            searchable=1,
            relationship='bodyCopy',
            widget=RichWidget
            (description='Please paste or type your article here',
                label='Body Copy',
                parastyles=(
                 ('div|pullQuote','Pull Quote'),
                 ('div|Caption','Caption'),
                 ('div|contactInformation','Contact Information'),
                 ('div|notesToEditors','Notes to editors'),
                ),
            ),
        ),

the ``ReftextField`` type is identical to the existing ``TextField``
except that it also extracts references from the HTML text whenever
the field is saved. The relationship used to hold the references may
be specified as shown, but if omitted it defaults to the field name.

If the HTML contains an invalid reference, e.g. a link to an object
that has since been deleted, ``ReftextField`` will completely ignore
that link.

Migrating from Epoz
-------------------

Epoz and Kupu will coexist: simply install both products. If you are
running an old version of Epoz you should either upgrade to a more
recent version, or ensure that the Kupu skin folders are searched
before the Epoz ones. Then encourage all your users to select Kupu as
their default editor from their user preferences.