CKeditor plugin

(3)

Used by approximately

of Grails users

Author(s)	Stefano Gualdi
Current Release	3.6.2.1 (2 weeks ago)
Grails Version	1.3 > *
License(s)	Apache License 2.0
Organization	Stefano Gualdi
Tags	editors
Dependency	compile ":ckeditor:3.6.2.1"

CKeditor web WYSIWYG editor integration plugin.

Installation
Description
Faq
Screenshots

Last updated by admin 2 years ago

grails install-plugin ckeditor

Last updated by stefano.gualdi 2 weeks ago

CKEditor Plugin

This plugin implements the integration layer between Grails and the new CKEditor web rich text editor.

This plugin can be used to integrate rich web editing functionality in Grails applications.

The plugin is written in Groovy/Grails without any dependencies on external libraries.

Current version

The versioning model has changed. Since version 3.3.2 the version number of the plugin will reflect the one of the underline integrated CKeditor library. If necessary a 4th level point release number will be used for successive changes on the plugin's code with same version of CKeditor.
Eg.
CKeditor release Initial plugin version Maintenance release
3.3.2 3.3.2 3.3.2.1
3.4 3.4.0 3.4.0.1

CKeditor release	Initial plugin version	Maintenance release
3.3.2	3.3.2	3.3.2.1
3.4	3.4.0	3.4.0.1

Current version is 3.6.2.1

Based on CKEditor (http://ckeditor.com) version 3.6.2

This version is developed and tested with Grails 1.3.7

License

This plugin is released under the Apache License, Version 2.0

Please refer to http://ckeditor.com/license for the licensing schemes provided by CKSource

Source code

The full source code for this plugin can be found on github: http://github.com/stefanogualdi/grails-ckeditor

For issues, improvements or new features go to the plugin's JIRA page

To contact me directly my email address is stefano DOT gualdi AT gmail DOT com

Also, feel free to send me any correction about this document. I'm not a native english speaker so please help me to correct the documentation.

Security

The plugin defines some url mappings to the controllers implementing the integration functionalities. If your application doesn't protect all the URIs you must ensure that such mappings are blocked to prevent unauthorized access.

Since version 3.4.0 the mappings are defined as follow:

/ck/standard/filemanager
/ck/standard/uploader
/ck/ofm/filemanager
/ck/ofm/filetree

in version 3.3.2:

/ckconnector
/ckuploader
/ofm/filemanager
/ofm/filetree

in versions before 3.3.2

/ckconnector
/ckuploader

The controllers names are:

since version 3.4.0:

openFileManagerConnector
standardFileManagerConnector

in version 3.3.2:

ckeditor
openFileManagerConnector

in versions before 3.3.2

ckeditor

Internal URI's customization

Since version 3.4.0.1 it is possible to customize the URI's used to invoke the plugin's connectors.

Eg:

ckeditor.connectors.prefix = "/my/app/ck/"

File browser

Since version 3.3.2 of the plugin is provided an integration with Open File Manager by Core Five Labs.

The plugin uses a modified version of the original code; you can find the initial version from Simogeo on github: http://github.com/simogeo/Filemanager while the modified version source is here: http://github.com/stefanogualdi/Filemanager.

Instruction to access the first version developed by Core Five Labs can be found here: http://www.corefive.com/News/Core_Five_Releases_Open_Source_FileManager_for_CKEditor/

Alternativaly this plugin is provided with an adapted version of the extended browser present in the FCKeditor Plugin.

Tags reference

The plugin defines the following custom tags:

Tag	Description
resources	Creates the necessary import for the CKEditor's javascripts files
config	Configure the editor instance
editor	Renders the wysiwyg editor
fileBrowser	Creates a link to open just the file browser
fileBrowserLink	Creates an URL to a file browser

all the tags belongs to the namespace ckeditor

Tag resources

This tag renders the javascript ref required to use the editor.

Must be used inside the head tag of the page in which you want to use the editor.

<html>
	<head>
		<ckeditor:resources />
	</head>	<body>
	</body>
</html>

By default the minified ckeditor's version will be loaded. Adding minified="false" will load the not minified, version. This can be useful for debugging purposes.

During the war generation the source will be stripped and the minified code will always be loaded.

Tag config

This tag give full access to every configuration option exposed by CKEditor.

The config tag provides two syntaxes for simple and complex option definition.

All the configuration options defined with this tag will be used in every editor instance defined after it.

Option names are case sensitive and must be written as indicated in the official documentation.

For a full reference of the available options please refer to the official documentation

Simple option

<ckeditor:config OptionName="option_value" />

Many options can be set in the same tag:

<ckeditor:config
    OptionOne="option_one_value"
    OptionTwo="option_two_value" />

Examples:

Set height and width for all the following editor's instances

<ckeditor:config
    height="300px"
    width="50%" />

Set the enter key handling strategy for all the following editor's instances

<ckeditor:config enterMode="CKEDITOR.ENTER_DIV" />

Complex option

<ckeditor:config var="option_name">
[structured_option_value]
</ckeditor:config>

Examples:

Define a new toolbar

<ckeditor:config var="toolbar_Mytoolbar">
[
    [ 'Source', '-', 'Bold', 'Italic' ]
]
</ckeditor:config>

Tag editor

This tag renders the wysiwyg editor in the page

<ckeditor:editor name="text">
Initial text
</ckeditor:editor>

available attributes are:

Attribute	Description
id	Id of the instance to be created. If not specified defaults to name
name	Field name (default: "editor")
userSpace	Name of the file user space to use for file browsing and uploads (default: "")
fileBrowser	File manager to use. Possible values: ofm, standard (default: "ofm")
viewMode	View mode for Open File Manager. Possible values: grid, list (default: "grid")
showThumbs	Show images' thumbnails in Open File Manager. Possible values: true, false (default: false)
removeInstance	Remove ckeditor instance before creation. Useful for ajax forms. Possible values: true, false (default: false)
options	Configuration options, as defined in the config tag section.

in the editor tag you can also specify every configuration option you like. Those options will be local to the instance that defines them.

Examples:

Renders an editor with custom size and a simple toolbar

<ckeditor:editor name="myeditor" height="400px" width="80%" toolbar="Basic">
${initialValue}
</ckeditor:editor>

Renders an editor with a custom toolbar defined in the page

<ckeditor:config var="toolbar_Mytoolbar">
[
    [ 'Source', '-', 'Bold', 'Italic' ]
]
</ckeditor:config><ckeditor:editor name="myeditor" toolbar="Mytoolbar">
${initialValue}
</ckeditor:editor>

For security reasons the userSpace attribute cannot contain any special character. Any invalid character will be removed.

Tag fileBrowser

Renders a link to open a stand alone file browser not associated with an editor instance

<ckeditor:fileBrowser>Open file browser</ckeditor:fileBrowser>

available attributes are:

Attribute	Description
type	Type of resource (default: "")
userSpace	Name of the file user space to use for file browsing and uploads (default: "")
fileBrowser	File manager to use. Possible values: ofm, standard (default: "standard")
viewMode	View mode for Open File Manager. Possible values: grid, list (default: "grid")
showThumbs	Show images' thumbnails in Open File Manager. Possible values: true, false (default: false)
target	Target attribute for the generated <A> tag (default: "")

if you just need the link to the file browser there is a fileBrowserLink tag:

<a href="${ckeditor:fileBrowserLink(type:'Image', userSpace:'userone')}">Open file browser</a>

If you want get back the path of the selected item in the file browser simply define a javascript function called ckeditorFileBrowserItemSelected in the page containing the opening link.

<script type="text/javascript" charset="utf-8">
	function ckeditorFileBrowserItemSelected(path) {
		// do whatever you want with path
		alert(path);
	}
</script>

Keep in mind that the stand alone file browser is designed to be opened in a separate browser window.

This option is only valid when using Open File Manager.

Configuration

The plugin can be configured with the standard Config.groovy file.

Actually are available the following options:

Config key	Default	Description
ckeditor.config	none	File name, relative to the webapp root, for the custom config file
ckeditor.skipAllowedItemsCheck	false	Skip the check on valid options names
ckeditor.defaulFileBrowser	none	Define the default file browser if not defined in tags. Possible values are: standard, ofm
ckeditor.upload.basedir	/uploads/	Base directory relative to webapp root if baseurl not defined, otherwise the absolute path where to store the uploaded files
ckeditor.upload.baseurl	none	The base URL to access the uploaded files
ckeditor.upload.enableContentController	false	Automatically create a mapping to view files when using baseurl setting
ckeditor.upload.overwrite	false	Overwite files on upload
ckeditor.upload.link.browser	false	Enable file browser for file objects
ckeditor.upload.link.upload	false	Enable upload tab for file objects
ckeditor.upload.link.allowed	[ ]	Extensions allowed for file objects
ckeditor.upload.link.denied	[ ]	Extensions denied for file objects
ckeditor.upload.image.browser	false	Enable file browser for image objects
ckeditor.upload.image.upload	false	Enable upload tab for image objects
ckeditor.upload.image.allowed	[ ]	Extensions allowed for image objects
ckeditor.upload.image.denied	[ ]	Extensions denied for image objects
ckeditor.upload.flash.browser	false	Enable file browser for flash objects
ckeditor.upload.flash.upload	false	Enable upload tab for flash objects
ckeditor.upload.flash.allowed	[ ]	Extensions allowed for flash objects
ckeditor.upload.flash.denied	[ ]	Extensions denied for flash objects

Sample config

ckeditor {
	config = "/js/myckconfig.js"
        skipAllowedItemsCheck = false
	defaultFileBrowser = "ofm"
	upload {
		basedir = "/uploads/"
	        overwrite = false
	        link {
	            browser = true
	            upload = false
	            allowed = []
	            denied = ['html', 'htm', 'php', 'php2', 'php3', 'php4', 'php5',
	                      'phtml', 'pwml', 'inc', 'asp', 'aspx', 'ascx', 'jsp',
	                      'cfm', 'cfc', 'pl', 'bat', 'exe', 'com', 'dll', 'vbs', 'js', 'reg',
	                      'cgi', 'htaccess', 'asis', 'sh', 'shtml', 'shtm', 'phtm']
	        }
	        image {
	            browser = true
	            upload = true
	            allowed = ['jpg', 'gif', 'jpeg', 'png']
	            denied = []
	        }
	        flash {
	            browser = false
	            upload = false
	            allowed = ['swf']
	            denied = []
	        }
	}
}

Security note
For security reasons it is important to define allowed/denied extensions.

Custom upload types

If you need to handle different types of uploads, since version 3.4.0, you can simply define a new block into the upload section:

…
upload {
	...	avatar {
	    browser = true
	    upload = true
	    allowed = ['gif', 'jpg']
	    denied = ['exe', 'sh', 'cgi']
	}
	…
}
...

Version history

3.6.2.1 (24/01/2012)

Fix for GPCKEDITOR-15

3.6.2.0 (24/01/2012)

Upgrade to CKEditor 3.6.2

3.6.0.0 (04/06/2011)

Upgrade to CKEditor 3.6
Upgrade to latest Open File Manager
Added viewMode tag to start the file manager in list or grid mode
Fix for GPCKEDITOR-13

3.5.4.1 (26/05/2011)

Fix for GPCKEDITOR-13

3.5.4.0 (21/05/2011)

Upgrade to CKEditor 3.5.4

3.5.3.0 (21/05/2011)

Upgrade to CKEditor 3.5.3
Upgrade to latest Open File Manager

3.5.2.0 (27/02/2011)

Upgrade to CKEditor 3.5.2
Upgrade to latest Open File Manager
Upgrade to Grails 1.3.7
Added id attribute to editor tag (Thanks to Paulo Alexandre Freitas)
Added removeInstance attribute to editor tag (Thanks to Paulo Alexandre Freitas)

3.4.1.0 (30/09/2010)

Upgrade to CKEditor 3.4.1

3.4.0.2 (21/09/2010)

Fixed file manager behaviour in windows

3.4.0.1 (05/09/2010)

Added CKEditor sources
Added minified attribute to resources tag
Several fixes on Open File Manager
Added internal URI's customization

3.4.0 (25/08/2010)

Upgrade to CKEditor 3.4
Added defaultFileBrowser setting
Added support for custom upload types
Added support for callback js function on file selection in stand alone file browser

3.3.2 (12/08/2010)

Upgrade to Grails 1.3.4
Upgrade to CKEditor 3.3.2
Fix for GRAILSPLUGINS-1946 (Open File Manager integration)
Fix for GRAILSPLUGINS-1948
Fix for GRAILSPLUGINS-2242
Fix for GRAILSPLUGINS-2292
Fix for GRAILSPLUGINS-2312
Fix for GRAILSPLUGINS-2375

0.6 (24/06/2010)

Upgrade to Grails 1.3.2
Upgrade to CKEditor 3.3.1

0.5 (02/06/2010)

Upgrade to Grails 1.3.1
Upgrade to CKEditor 3.3

0.4 (20/04/2010)

Upgrade to Grails 1.2.2
Upgrade to CKEditor 3.2.1

0.3 (10/02/2010)

Upgrade to Grails 1.2.1
Upgrade to CKEditor 3.1 (GRAILSPLUGINS-1849)
Fix for GRAILSPLUGINS-1942

0.2 (05/01/2010)

Upgrade to Grails 1.2.0
Upgrade to CKEditor 3.0.2

0.1 (04/11/2009)

First public release

Last updated by admin 2 years ago