======================== Installing Kupu in Plone ======================== .. contents:: Table of Contents :depth: 2 :backlinks: top .. sectnum:: :depth: 2 Requirements ------------ * Zope 2.7.3 and Python 2.3.3 or greater * Plone 2.0 or greater * CMF 1.4 or greater * Archetypes 1.3.9 or greater If you plan on customizing kupu by editing the '.kupu' files 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, or simply checking it out from SVN to use in Plone. Installation ------------ Drop the 'kupu' directory into your instance home's Products directory. If you are installing from a release tar bundle, or simply checking out kupu to use in Plone and not to edit then the following build steps may be skipped. Skip down to the paragraph starting `Now restart the Zope instance`_. If you edit any of the files with .kupu extensions then you must re-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 would require an extra hit on the server, and will contain the internal UID so a transform is installed for any field which has text/x-safe-html or text/x-html-captioned as its output format. (`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. Links which are redirected use Kupu's transform to correct the URL when the page is rendered in view mode, but in edit mode the links use the resolveuid script to resolve as they are accessed. This involves an additional hit through the server. If a UID link does not have a UID which is currently valid then Kupu will look for an additional script kupu_resolveuid_hook. This script may be used to lookup the UIDs in an external system, or to provide a customised error page for broken UID links. To point all broken links to a specific URL you could for example invent a dummy object:: from Products.PythonScripts.standard import Object def absurl(): return '[insert url of broken link page here]' def Title(): return 'This link is broken' return Object(absolute_url=absurl, absolute_url_path=absurl, Title=Title, Description=Description,) 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``. Styles :::::: Enter a list of styles to be added to the style pulldown. See `Custom 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. containsanchors This entry lists content types which could contain internal HTML anchors. The link drawer will offer the 'anchors' button to retrieve the anchors for content of this type. In addition, when used with Archetypes content, a resource type can be the name of an Archetypes field (in the form 'portal type.field name'). See `Reference Browser`_. Action urls ~~~~~~~~~~~ For any type (but mostly images) you may specify expressions to be used for the preview in the drawer properties panel, the url to be inserted for a normal image, and the field to be used to determine image scales. The defaults are: preview No preview shown by default. Set to 'string:${object_url}/image_thumb' for an image preview. object_url for the preview is the actual url of the object. normal image Defaults to 'string:${object_url}'. object_url for the normal url will be the resolveuid form if uids are being used, otherwise the actual url. fieldname Defaults to 'image'. N.B. This is a literal string, not a tal expression. default scale Defaults to 'image_preview'. Use either blank or 'original' for full size images. classes An optional list of class names to be allowed for this media type. The class names will be applied in addition to left/inline/right and captioned class names. type This controls whether kupu inserts an img tag or an object tag. Only images and flash objects are supported at this time. 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. links tab ========= This tab allows you to check and maintain links in kupu-editable fields. Type (Field Name) Lists content types and field names which are editable using Kupu. Only those content types which are exist in the catalog are listed. Folders You may use the popup to restrict the search to one or more folders. If you do not select a folder the entire site will be searched. Info This field lists the number of matching objects in the catalog based on the current type and folder selection. There are three command buttons: check links, relative path -> uids, and uids -> relative path. You should convert relative path to uids if you are enabling the 'link by uid' option and have existing content, or if you have imported content from another source which contains relative links. The 'uid to relative path' conversion is useful if you have decided to stop using 'link by uid' or if you wish to transfer content to another system and uids might not preserved during the process. Also, if you want to copy a folder within Plone convert to relative paths before copying and convert both folders back to uids after copying will ensure wherever appropriate that any links within the copied folder point to the copy rather than the original. All commands look for links in the HREF attribute of A tags, and the SRC attribute of IMG tags in the selected field. Only relative URLs are processed: links to other sites or for other protocols are not checked. Pressing a command button should load the results page and then after a short pause should start searching. A progress bar indicates how the search is progressing. check links This command does not modify any content. It simply lists all relative links which are not obviously valid. It is possible that some of these links are correct. Each potentially bad link is displayed with a link to the URL to which Kupu believes it refers. You should review the links individually within the documents and fix them as required. Links to methods within objects (except for the difference image sizes) may also be flagged as potential errors. relative path -> uids This button searches for all relative path URLs which could be replaced by references using the resolveuid form of link. Nothing is actually changed at this point. Each title link has a checkbox and you may de-select any which you wish to be left unchanged: you may only control the changes at the field level, you cannot choose to apply only some of the changes within a field. Changes will only be made when you press the 'commit selected changes' button. The proposed changes are displayed with deleted and inserted text highlighted appropriately. If you confirm the changes then the resulting text is displayed with the change highlighted. uids -> relative path This command searches for all resolveuid links and replaces them with normal relative urls. As with the previous command you are given a screen showing the proposed changes and may exclude any of them before confirming the search. toolbar tab =========== This tab allows you to control which buttons and groups of buttons are displayed on the kupu toolbar. N.B. Be carefule, some combinations of buttons may render kupu hard to use. You may hide a button or group completely simply by unchecking the appropriate ``visible`` checkbox in this page. A button can only be visible if the group which contains it is also visible. You may enter an expression to control whether a button should be visible, e.g. to restrict buttons based on the user's roles. If there is an expression for a button the setting of the checkbox is ignored. The following values are available within the expression context: field object_url folder_url portal_url object folder portal nothing request modules member The visibility of buttons may be further controlled within the widget definition for a field, but the this can only hide buttons, it cannot force a button to display if the settings on this tab have made it invisible. The widget allows for either a whitelist ``allow_buttons`` attribute or a blacklist ``filter_buttons``. Either attribute should contain a list or tuple of button or group ids. The available ids are listed on the toolbar tab. If the widget has an attribute ``allow_buttons`` then only buttons and groups listed in this attribute will be visible; all other buttons are hidden. If there is no ``allow_buttons`` attribute (or its value is ``None`` then all buttons are allowed unless excluded by ``filter_buttons``. This example would hide all buttons except for bold, italic, left and right justify:: TextField('text', allowable_content_types=('text/html',), default_output_type='text/x-html-safe', required=1, widget=RichWidget (label='Content', allow_buttons=( 'bg-basicmarkup', 'bold-button', 'italic-button', 'bg-justify', 'justifyleft-button', 'justifyright-button', ), ), ), This example would hide only the zoom button:: TextField('text', allowable_content_types=('text/html',), default_output_type='text/x-html-safe', required=1, widget=RichWidget (label='Content', filter_buttons=('zoom', ), ), ), N.B. Toolbar buttons which are disabled in Plone's default configuration may represent tools which are not fully integrated into Plone. If you wish to use these tools and find problems with them you should submit a patch. Custom styles ------------- Kupu allows you to specify styles for paragraphs (P or DIV tags), character styles (SPAN tags), and table elements (TABLE, THEAD, TBODY, TFOOT, TR, TH, TD tags). The table styles are only available while the cursor is inside a table, other styles are available at all times. 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 `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 Highlight|span|highlight Table Head|th Each rich text field can define its own set of 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', redefine_parastyles=False, parastyles=( 'Pull Quote|div|pullQuote', 'Caption|div|caption', 'Contact Information|div|contactInformation', 'Notes to editors|div|notesToEditors', ), ), ), ``parastyles`` is a sequence of style definitions. Each definition should be a string as for the style definitions in the control panel containing the description that appears in the style pulldown, vertical bar, the tag to be added, vertical bar, class to be assigned to the tag. The class may be omitted, so description, vertical bar, tag is also valid. If the widget has an attribute ``redefine_parastyles`` which is true, then the styles defined for the field will replace the globally configured styles. If false or not set the field styles are added to the global styles. 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 have 'link by uid' enabled in the configuration options, and the field you are editing must invoke the html-to-captioned output transform. The field must have a default output type of text/x-html-safe or text/x-html-captioned otherwise image drawer will not include the caption option. 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. There are (at least) 2 ways to arrange this. One way is that the field should have its ``default_output_type`` set to ``text/x-html-captioned`` in the Archetypes schema. The problem with this is that the default ATContentTypes use an output type of 'text/x-html-safe'. If either link by uid or captioning is enabled then Kupu will attempt to configure the Portal Transform engine to apply the transform automatically. If you have a version of Portal Transforms earlier than 1.3.9 then you may need to patch it to work correctly with the transform: Find the line:: requirements = self._policies.get(target_mt, []) and change it to:: requirements = self._policies.get(str(target_mt), []) Once you have done kupu will configure the portal_transforms tool as follows: * add a new transform id 'captioned_to_html', module 'Products.PortalTransforms.transforms.identity' with input type text/x-html-captioned and output type text/html. * On the portal_transforms policy tab add a policy with output type=text/x-html-safe, uses transforms='html-to-captioned'. This will force the captioning transform to be applied before the safe_html transform. 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:: is replaced by::
...description text...
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; } Flash ----- Kupu has some support for embedding Flash objects using the ATFlashMovie content type, but requires some configuration. Other Flash content types may also work but have not been tested. 1. Install ATFlashMovie. 2. Got to the resource types tab of the configlet. 3. Under the resource ``mediaobject`` add Flash Movie to the selection and save. 4. In the action urls table at the bottom of the page, add a new entry for the type Flash Movie. The preview may be left blank or be the same as the 'normal' image. For 'normal image' you should enter ``string:${object_url}/download``. Leave fieldname blank and in the 'type' field select 'Flash'. Flash movies should now appear in the image drawer and be insertable into the document. Using IE the Flash movie will appear in the document and may be edited or moved as desired. Firefox will not play the movie while you are editing, so a 'flash placeholder' image is displayed instead: you cannot select it in Firefox so if you need to delete a Flash movie you will need to include the image in a slightly larger selection (e.g. spaces before and after) and delete that. Known problems ============== When selecting a flash object in IE you need to be sure to get a selection only with sizing handles (by clicking exactly on the edge). If the selection box also shows cross-hatched then you have clicked inside the Flash object and kupu will not be able to determine the current selection. In IE the Flash object sometimes appears over the top of the drawer. Workaround: close the drawer and try again. 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', ), ), ), 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. Reference Browser ----------------- Kupu will replace the popup windows used by ATReferenceBrowser with its own drawers. When used as a reference browser, the attributes of the field and widget are used as Kupu's resource type. The following attributes are recognised: allowed_types Direct equivalent of Kupu's own resource types. Lists permitted types for the drawer. allowed_types_method The name of a method on the object which can be called to return the list of types. base_query Either a dictionary, or the name of a method which returns a dictionary. This dictionary contains search parameters used by libraries. 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.