[Sommaire] [Imprimer]

   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.