Introduction

This addon is a ckeditor integration for Plone. This release includes ckeditor version 4.20.2.

Contents

• Introduction
• How to install
  • Dependencies
• Translations
• Upgrades
  • 4.3.0
• CKEditor plugins
  • balloontoolbar plugin
  • uploadimage plugin
  • nonbreaking plugin
  • tableresize plugin
• Development
  • How to Release
  • How to update to a newer version of CKEditor
  • Tests status
• Credits
  • Companies
  • Contributors

How to install

You can install it as any Plone addon. Please follow official documentation.

The code source can be found at https://github.com/collective/collective.ckeditor

Please report issues at https://github.com/collective/collective.ckeditor/issues

Dependencies

• Plone >= 4
• collective.plonefinder

Translations

This product has been translated into

• Spanish.
• French.
• Italian.

You can contribute for any message missing or other new languages, join us at Plone Collective Team into Transifex.net service with all world Plone translators community.

Upgrades

Go to ZMI-->portal_setup-->Upgrades, choose "collective.ckeditor:default" profile and execute the upgrade steps.

4.3.0

Release 4.3.0 comes with the Enhanced Image plugin (image2). It is not enabled by default as it removes some of the advanced functionality provided by the default image plugin (image). However, the Enhanced Image plugin provides the ability to add a caption together with the image. It is also much more user-friendly.

To enable the plugin, you need to setup ckeditor_properties through generic setup propertiestool.xml:

<?xml version="1.0"?>
<object name="portal_properties" meta_type="Plone Properties Tool">
 <object name="ckeditor_properties" meta_type="Plone Property Sheet">
  <property name="removePlugins" type="lines">
   <element value="image"/>
  </property>
  <property name="plugins" type="lines">
   <element value="ajaxsave;/++resource++cke_ajaxsave/plugin.js"/>
   <element value="image2;/++resource++ckeditor/plugins/image2/plugin.js"/>
  </property>
 </object>
</object>

This disables the image (default) plugin and enables the image2 plugin.

The image2 plugin comes with two specific settings (configurable only through generic setup):

<?xml version="1.0"?>
<object name="portal_properties" meta_type="Plone Properties Tool">
 <object name="ckeditor_properties" meta_type="Plone Property Sheet">
  <property name="image2_captionedClass" type="string">image</property>
  <property name="image2_alignClasses" type="lines">
   <element value="image-left"/>
   <element value="image-dummy"/>
   <element value="image-right"/>
  </property>
 </object>
</object>

The settings are image2_captionedClass and image2_alignClasses. The values above are the default values.

If you enable the plugin, you also need to setup Plone to accept the figcaption tag.

This is done by configuring HTML filtering with a setup handler like:

def enable_figcaption(p):
    """ Allow figcaption as valid tag in portal_transforms safe_html"""

    from Products.PortalTransforms.Transform import make_config_persistent

    pt = getToolByName(p, 'portal_transforms')
    tid = 'safe_html'
    if not tid in pt.objectIds():
        return
    trans = pt[tid]
    tconfig = trans._config

    validtags = tconfig['valid_tags']
    validtags.update({'figcaption': 1})

    make_config_persistent(tconfig)
    trans._p_changed = True
    trans.reload()
    log.info('added figcaption as valid tag')

CKEditor plugins

balloontoolbar plugin

provided since version 4.8.0

Not enabled by default, this plugin provides an API to setup context sensitive toolbars.

To enable the plugin, add balloontoolbar;/++resource++ckeditor/plugins/balloontoolbar/plugin.js to the Plugins field in CKEditor control panel (@@ckeditor-controlpanel).

uploadimage plugin

provided since version 4.7.0

Enabled by default, this plugin manages support for uploading images that were dropped or pasted into the editor.

nonbreaking plugin

provided since version 4.4.5.

When enabled, the plugin provides keyboard shortcuts to insert non breaking chars:

• Ctrl-Alt-Space for non breaking space,
• Ctrl-Alt-Hyphen for non breaking hyphen.

Corresponding buttons can also be configured in the toolbar:

• NbSpace
• NbHyphen

To enable the plugin, add nonbreaking;/++resource++cke_nonbreaking/plugin.js to the Plugins field in CKEditor control panel (@@ckeditor-controlpanel).

Or setup ckeditor_properties through generic setup propertiestool.xml:

<?xml version="1.0"?>
<object name="portal_properties" meta_type="Plone Properties Tool">
 <object name="ckeditor_properties" meta_type="Plone Property Sheet">
  <property name="plugins" type="lines">
   <element value="ajaxsave;/++resource++cke_ajaxsave/plugin.js"/>
   <element value="nonbreaking;/++resource++cke_nonbreaking/plugin.js"/>
  </property>
 </object>
</object>

tableresize plugin

When enabled, the plugin makes it easy to change the table columns width by drag/dropping it from left to right and right to left.

To enable the plugin, add tableresize;/++resource++ckeditor/plugins/tableresize/plugin.js to the Plugins field in CKEditor control panel (@@ckeditor-controlpanel).

Or setup ckeditor_properties through generic setup propertiestool.xml:

<?xml version="1.0"?>
<object name="portal_properties" meta_type="Plone Properties Tool">
 <object name="ckeditor_properties" meta_type="Plone Property Sheet">
  <property name="plugins" type="lines" purge="False">
   <element value="tableresize;/++resource++ckeditor/plugins/tableresize/plugin.js"/>
  </property>
 </object>
</object>

Development

Attention!

ConfigurationError

If you try to run a Zope/Plone instance with a collective.ckeditor checkout, your instance will break with a ConfigurationError:

Directory .../browser/ckeditor does not exist.

After checking out collective.ckeditor sources, run the included buildout.

This installs and runs the copy_ckeditor_code script. It takes care of copying ckeditor code in the appropriate browser/ckeditor directory.

The browser/ckeditor directory makes ckeditor javascript code available to the browser at:

http://yourplonesite/++resource++ckeditor/

How to Release

Obviously, the ckeditor code also needs to be included in the released eggs.

collective.ckeditor registers an entry point for zest.releaser that (if called properly) takes care of copying the code when preparing the release.

However, in order to take advantage of the entry point, you have to use the bin/fullrelease locally installed by the development buildout instead of a globally installed fullrelease.

Only the local bin/fullrelease script can see the entry_point registered by collective.ckeditor.

How to update to a newer version of CKEditor

Valid for CKEditor 4

1. Go to dev/build-ckeditor
2. Update plugin versions

• Check current version of plugins according to the new CKEditor version. See here for example : https://ckeditor.com/cke4/addon/image2
• Update plugin versions computation
  • "Enhanced Image" in image2.sh
  • "Moono Color" in moono.sh
  • "SpellCheckAsYouType (SCAYT)" in scayt.sh

3. Issue the following command CKEDITOR_VERSION=4.x.x make
4. Go to the package root and run bin/copy_ckeditor_code
5. Test
6. Add untracked files git add ../../src/collective/ckeditor/_src/ckeditor/
7. Commit

If you need unminified JS to debug the release, step 3 can be replaced with:

MINIFIED_JS=--leave-js-unminified CKEDITOR_VERSION=4.x.x make

Tests status

This add-on is tested using Travis CI. The current status of the add-on is:

Credits

Companies

• Makina Corpus
• Ecreall
• BubbleNet
• Hexagonit
• Plone 5 support funded by Imio
• Plone 6 support funded by KULeuven

Contributors

• Kai Lautaportti <kai.lautaportti@hexagonit.fi>
• Giacomo Spettoli <giacomo.spettoli@gmail.com>
• Godefroid Chapelle <gotcha@bubblenet.be>
• Mathieu Le Marec - Pasquet <kiorky@cryptelium.net>
• Jean-Mat Grimaldi <jeanmat.grimaldi@gmail.com>
• Michael Smith <msmith64@naz.edu>
• Victor Fernandez de Alba <sneridagh@gmail.com>
• Kim Paulissen <spereverde@gmail.com>
• Jean-Michel FRANCOIS aka toutpt <toutpt@gmail.com>
• Gauthier Bastien <gauthier@imio.be>
• Leonardo J. Caballero G. <leonardocaballero@gmail.com>