CKEditor for Java Integration Guide

This website contains links to software which is either no longer maintained or will be supported only until the end of 2019 (CKFinder 2). For the latest documentation about current CKSource projects, including software like CKEditor 4/CKEditor 5, CKFinder 3, Cloud Services, Letters, Accessibility Checker, please visit the new documentation website.

If you look for an information about very old versions of CKEditor, FCKeditor and CKFinder check also the CKEditor forum, which was closed in 2015. If not, please head to StackOverflow for support.

(→‎Using the Tag on the Page: - corrected basePath)
Line 11: Line 11:
  
 
=== Using Maven2 ===
 
=== Using Maven2 ===
 +
<note>The following method is not yet available, please follow the manual installation.
 +
</note>
 
If your application uses Maven, you can add the following dependency to your <code>pom.xml</code> file:
 
If your application uses Maven, you can add the following dependency to your <code>pom.xml</code> file:
 
<source lang="xml">
 
<source lang="xml">

Revision as of 16:22, 2 May 2011

Adding CKEditor to your application is a two-step process that entails:

  1. downloading standalone CKEditor and placing it in the web application directory,
  2. downloading and installing the server-side integration (CKEditor for Java).

Adding Client-Side CKEditor Sources

Go to the official CKEditor download site and grab the latest version of CKEditor. Place it in the directory of your web application.

Adding Tag Library (ckeditor-java-core)

When you want to add the CKEditor library, you can choose between using Maven and adding it manually.

Using Maven2

important note

The following method is not yet available, please follow the manual installation.

If your application uses Maven, you can add the following dependency to your pom.xml file: 

<dependency>
	<groupId>com.ckeditor</groupId>
	<artifactId>ckeditor-java-core</artifactId>
	<version>3.x.y</version>
</dependency>

Please note that 3.x.y denotes the artifact version, like <version>3.6</version>. Since CKEditor releases are added to the central Maven repository, the specified version should be downloaded automatically.

Without Maven

If you do not use Maven, you have to add the CKEditor jar library manually. Go to the CKEditor download site, download the ckeditor-java-core-*ver.jar file, and put it in your /WEB-INF/lib directory.

important note

Please note that *ver denotes the version of a CKEditor release.


Using the Tag on the Page

CKEditor replaces the HTML textarea element(s) with its instance(s). Unless you are using the <ckeditor:editor> tag (which will be described later), the first thing you need is a JSP page with an HTML textarea element.

For the purpose of this article let us assume that the page looks like this: 

<!DOCTYPE unspecified PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<%@page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%>
<html>
	<body>
		<form action="sample_posteddata.jsp" method="get">
			<p>
				<label for="editor1">Editor 1:</label>
				<textarea cols="80" id="editor1" name="editor1" rows="10"></textarea>
			</p>
			<p>
				<input type="submit" value="Submit" />
			</p>
		</form>
	</body>	
</html>

As seen in the code above, the action attribute of the form element contains the sample_posteddata.jsp value. This is a web.xml mapping that is used in the samples and points to a servlet that prints the contents of CKEditor, when the page is submitted.

When the JSP page is ready, you need to declare the CKEditor tag library inside it: 

<%@ taglib uri="http://ckeditor.com" prefix="ckeditor" %>

Next you have to add the CKEditor tag (<ckeditor:replace> in this case) to the page. It is recommended to add it at the end, just before the closing </body> tag: 

<ckeditor:replace  replace="editor1" basePath="/ckeditor/" />

Please note that the CKEditor tag above contains two attributes:

  • replace – points to the name or ID of the HTML textarea element that is to be replaced with a CKEditor instance.
  • basePath – contains the path to the main CKEditor directory.
    If, for example, your JSP code containing the CKEditor tag is placed in the Webapp/jsp/page.jsp file, and CKEditor is located in the /Webapp/ckeditor directory, the basePath attribute should point to ../ckeditor or /Webapp/ckeditor/.
    Another example
    if CKEditor is available under http://example.com/3rdparty/ckeditor/, the basePath attribute should be set to /3rdparty/ckeditor/.

For the purpose of this document it is assumed that CKEditor is available in the /ckeditor/ directory (http://example.com/ckeditor/).

Please note that other tag attributes are also available. Refer to the Common Tag Attributes section below for a full description.

Below is the full source code of our sample page: 

<!DOCTYPE unspecified PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<%@page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%>
<%@ taglib uri="http://ckeditor.com" prefix="ckeditor" %>
<html>
	<body>
		<form action="sample_posteddata.jsp" method="get">
			<p>
				<label for="editor1">Editor 1:</label>
				<textarea cols="80" id="editor1" name="editor1" rows="10"></textarea>
			</p>
			<p>
				<input type="submit" value="Submit" />
			</p>
		</form>
	<ckeditor:replace  replace="editor1" basePath="/ckeditor/" />
	</body>	
</html>

Common Tag Attributes

The list below presents some of the commonly used tag attributes.

  • timestamp – this parameter stores the value specific for a particular CKEditor release, which helps to avoid browser caching problems when a new client-side CKEditor version is uploaded to the server.
  • initialized – setting this parameter to true means that the ckeditor.js script from CKEditor is already included in the page and there is no need to add it again. Setting it to false, on the other hand, means that the ckeditor.js script should be added to the page.
  • config – this parameter contains the CKEditor configuration object. For the list of available options, please refer to the JavaScript API.
    Configuration options are stored in the CKEditorConfig object. They are added by using the addConfigValue method
<% 
	CKEditorConfig config2 = new CKEditorConfig();
	config2.addConfigValue("width","500");
%>

The first parameter of this method is always the name of a configuration option in the form of a string. The second one is the value of this option for which a String, Boolean, Number, List, or Map object can be used. No matter what type is used, CKEditor will try to map each value to an acceptable form. For example, the code below: 

<% 
	CKEditorConfig config2 = new CKEditorConfig();
	config2.addConfigValue("toolbar","[[ 'Source', '-', 'Bold', 'Italic' ]]");
%>

is equal to: 

<% 
	CKEditorConfig config2 = new CKEditorConfig();
	List<List<String>> list = new ArrayList<List<String>>();
	List<String> subList = new ArrayList<String>();
	subList.add("Source");
	subList.add("-");
	subList.add("Bold");
	subList.add("Italic");
	list.add(subList);
	config2.addConfigValue("toolbar", list);
%>
  • events – this parameter stores the list of client-side event listeners and is of com.ckeditor.EventHandler type.
    Example
    Firstly, an instance of the EventHandler has to be created. Then you can add events by using the addEvent method, where the first parameter is the CKEditor event keyword and the second one is the JavaScript function in the form of a concatenated string. 
<% 
	EventHandler eventHandler = new EventHandler();
	eventHandler.addEvent("instanceReady","function (ev) { alert(\"Loaded: \" + ev.editor.name); }");
%>
  • In order to use the events on a page, the following expression can be added
<ckeditor:editor basePath="/ckeditor/" editor="editor1" events="<%=eventHandler %>"/>
  • globalEvents – this parameter stores the list of client-side event listeners that are used by all CKEditor instances and is of GlobalEventHandler type.
<%
	GlobalEventHandler globalEventHandler = new GlobalEventHandler();
	globalEventHandler.addEvent("dialogDefinition","function (ev) { alert(\"Loading dialog window: \" + ev.data.name); }");
%>

Instances of the configuration, events, and global events can be created either in a scriptlet, or in a separated Java class. Here is an example: 

package com.ckeditor.samples;

import java.util.ArrayList;
import java.util.List;

import com.ckeditor.CKEditorConfig;
import com.ckeditor.EventHandler;
import com.ckeditor.GlobalEventHandler;

public class ConfigurationHelper {

	
	public static CKEditorConfig createConfig() {
		CKEditorConfig config = new CKEditorConfig();
		List<List<String>> list = new ArrayList<List<String>>();
		List<String> subList = new ArrayList<String>();
		subList.add("Source");
		subList.add("-");
		subList.add("Bold");
		subList.add("Italic");
		list.add(subList);
		config.addConfigValue("toolbar", list);
		config.addConfigValue("width","500");
		return config;
	}
	
	public static EventHandler createEventHandlers() {
		EventHandler handler = new EventHandler();
		handler.addEvent("instanceReady","function (ev) { alert(\"Loaded: \" + ev.editor.name); }");
		return handler;
	}
	
	public static GlobalEventHandler createGlobalEventHandlers() {
		GlobalEventHandler handler = new GlobalEventHandler();
		handler.addEvent("dialogDefinition","function (ev) {  alert(\"Loading dialog window: \" + ev.data.name); }");
		return handler;
	}
}

To access this class on a JSP page you can use the following expression: 

<ckeditor:replace replace="editor1" basePath="ckeditor/"
   config="<%= ConfigurationHelper.createConfig() %>"
   events="<%= ConfigurationHelper.createEventHandlers() %>" />

Other Use Cases for CKEditor Tags

The examples in this section show some more usage scenarios for CKEditor for Java tags.

Creating a CKEditor Instance

The <ckeditor:editor> tag creates a CKEditor instance. 

<ckeditor:editor textareaAttributes="<%=attr %>" initialized="false"
   basePath="/ckeditor/" config="<%=config2 %>" editor="editor1" value="Type here" />

For this tag no HTML textarea element needs to be present on a page. It is created internally and immediately replaced with a CKEditor instance. The code above contains the following elements:

  • basePath – is the relative path to the main CKEditor directory (see <ckeditor:replace> for details).
  • editor – is the name of the internal textarea element.
  • value – is the default textarea element value.
  • textareaAttributes – is a java.util.Map with textarea attribute names serving as map keys, and attribute values serving as map values. For example:
<% 
	Map<String, String> attr = new HashMap<String, String>();
	attr.put("rows", "8");
	attr.put("cols", "50");
%>
important note
These attributes are not validated. If you put an incorrect attribute name or value into the map, you might get an HTML error or the page may not be rendered properly.


Replacing All Textarea Elements

The <ckeditor:replaceAll> tag replaces all textarea elements available in the document with editor instances. Optionally it can replace only the textarea elements that have a CSS class equal to the value of the CKEditor className attribute. 

<ckeditor:replaceAll basePath="/ckeditor/" className="myclass"/>

This tag changes all textarea elements with a CSS class of myclass to CKEditor instances.

Retrieved from "https://docs-old.ckeditor.com/index.php?title=CKEditor_3.x/Developers_Guide/Java/Integration&oldid=6246"