J.swiderski (talk | contribs) |
(Source code formatting changed) |
||
(2 intermediate revisions by 2 users not shown) | |||
Line 33: | Line 33: | ||
To start using <code><ckeditor></code> tags in your JSP page, you need to declare the CKEditor tag library inside it: | To start using <code><ckeditor></code> tags in your JSP page, you need to declare the CKEditor tag library inside it: | ||
− | <source lang=" | + | <source lang="java"> |
<%@ taglib uri="http://ckeditor.com" prefix="ckeditor" %> | <%@ taglib uri="http://ckeditor.com" prefix="ckeditor" %> | ||
</source> | </source> | ||
Line 62: | Line 62: | ||
Next you have to add the CKEditor tag (<code><ckeditor:replace></code> in this case) to the page. It is recommended to add it at the end, just before the closing <code></body></code> tag: | Next you have to add the CKEditor tag (<code><ckeditor:replace></code> in this case) to the page. It is recommended to add it at the end, just before the closing <code></body></code> tag: | ||
− | <source lang=" | + | <source lang="java"> |
<ckeditor:replace replace="editor1" basePath="/ckeditor/" /> | <ckeditor:replace replace="editor1" basePath="/ckeditor/" /> | ||
</source> | </source> | ||
Line 97: | Line 97: | ||
=== Replacing All Textarea Elements === | === Replacing All Textarea Elements === | ||
The <code><ckeditor:replaceAll></code> tag replaces all <code>textarea</code> elements available in the document with editor instances. Optionally it can replace only the <code>textarea</code> elements that have a CSS class equal to the value of the CKEditor <code>className</code> attribute. | The <code><ckeditor:replaceAll></code> tag replaces all <code>textarea</code> elements available in the document with editor instances. Optionally it can replace only the <code>textarea</code> elements that have a CSS class equal to the value of the CKEditor <code>className</code> attribute. | ||
− | <source lang=" | + | <source lang="java"> |
<ckeditor:replaceAll basePath="/ckeditor/" className="myclass"/> | <ckeditor:replaceAll basePath="/ckeditor/" className="myclass"/> | ||
</source> | </source> | ||
Line 105: | Line 105: | ||
=== Creating a CKEditor Instance === | === Creating a CKEditor Instance === | ||
The <code><ckeditor:editor></code> tag creates a CKEditor instance. | The <code><ckeditor:editor></code> tag creates a CKEditor instance. | ||
− | <source lang=" | + | <source lang="java"> |
<ckeditor:editor textareaAttributes="<%=attr %>" basePath="/ckeditor/" editor="editor1" value="Type here" /> | <ckeditor:editor textareaAttributes="<%=attr %>" basePath="/ckeditor/" editor="editor1" value="Type here" /> | ||
</source> | </source> | ||
Line 114: | Line 114: | ||
* <code>value</code> – is the default <code>textarea</code> element value. | * <code>value</code> – is the default <code>textarea</code> element value. | ||
* <code>textareaAttributes</code> – is a <code>java.util.Map</code> with textarea attribute names serving as map keys, and attribute values serving as map values. For example: | * <code>textareaAttributes</code> – is a <code>java.util.Map</code> with textarea attribute names serving as map keys, and attribute values serving as map values. For example: | ||
− | <source lang=" | + | <source lang="java"> |
<% | <% | ||
Map<String, String> attr = new HashMap<String, String>(); | Map<String, String> attr = new HashMap<String, String>(); | ||
Line 134: | Line 134: | ||
Configuration options are stored in the <code>CKEditorConfig</code> object. They are added by using the <code>addConfigValue</code> method: | Configuration options are stored in the <code>CKEditorConfig</code> object. They are added by using the <code>addConfigValue</code> method: | ||
− | <source lang=" | + | <source lang="java"> |
<% | <% | ||
CKEditorConfig settings = new CKEditorConfig(); | CKEditorConfig settings = new CKEditorConfig(); | ||
Line 143: | Line 143: | ||
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: | 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: | ||
− | <source lang=" | + | <source lang="java"> |
<% | <% | ||
CKEditorConfig settings = new CKEditorConfig(); | CKEditorConfig settings = new CKEditorConfig(); | ||
Line 150: | Line 150: | ||
</source> | </source> | ||
is equal to: | is equal to: | ||
− | <source lang=" | + | <source lang="java"> |
<% | <% | ||
CKEditorConfig settings = new CKEditorConfig(); | CKEditorConfig settings = new CKEditorConfig(); | ||
Line 163: | Line 163: | ||
%> | %> | ||
</source> | </source> | ||
− | + | ==== New CKEditor 3.6 Toolbar Syntax ==== | |
− | As of CKEditor 3.6, | + | As of CKEditor 3.6, toolbar buttons can be [[CKEditor_3.x/Developers_Guide/Toolbar#Toolbar_Button_Groups|organized into groups]]. Each group has its own name and a set of buttons that it includes. The new definition can also be expressed in two ways. |
− | The below | + | |
− | <source lang=" | + | The code below: |
+ | <source lang="java"> | ||
<% | <% | ||
CKEditorConfig settings = new CKEditorConfig(); | CKEditorConfig settings = new CKEditorConfig(); | ||
Line 174: | Line 175: | ||
</source> | </source> | ||
is equal to: | is equal to: | ||
− | <source lang=" | + | <source lang="java"> |
<% | <% | ||
CKEditorConfig settings = new CKEditorConfig(); | CKEditorConfig settings = new CKEditorConfig(); | ||
Line 209: | Line 210: | ||
==== Example: ==== | ==== Example: ==== | ||
Firstly, an instance of the <code>EventHandler</code> has to be created. Then you can add events by using the <code>addEvent</code> 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. | Firstly, an instance of the <code>EventHandler</code> has to be created. Then you can add events by using the <code>addEvent</code> 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. | ||
− | <source lang=" | + | <source lang="java"> |
<% | <% | ||
EventHandler eventHandler = new EventHandler(); | EventHandler eventHandler = new EventHandler(); | ||
Line 217: | Line 218: | ||
In order to use the events on a page, the following expression can be added: | In order to use the events on a page, the following expression can be added: | ||
− | <source lang=" | + | <source lang="java"> |
<ckeditor:editor basePath="/ckeditor/" editor="editor1" events="<%=eventHandler %>"/> | <ckeditor:editor basePath="/ckeditor/" editor="editor1" events="<%=eventHandler %>"/> | ||
</source> | </source> | ||
Line 223: | Line 224: | ||
=== <code>globalEvents</code> === | === <code>globalEvents</code> === | ||
<code>globalEvents</code> – this parameter stores the list of client-side event listeners that are used by all CKEditor instances and is of <code>GlobalEventHandler</code> type. | <code>globalEvents</code> – this parameter stores the list of client-side event listeners that are used by all CKEditor instances and is of <code>GlobalEventHandler</code> type. | ||
− | <source lang=" | + | <source lang="java"> |
<% | <% | ||
GlobalEventHandler globalEventHandler = new GlobalEventHandler(); | GlobalEventHandler globalEventHandler = new GlobalEventHandler(); | ||
Line 274: | Line 275: | ||
To access this class on a JSP page you can use the following expression: | To access this class on a JSP page you can use the following expression: | ||
− | <source lang=" | + | <source lang="java"> |
<ckeditor:replace replace="editor1" basePath="ckeditor/" | <ckeditor:replace replace="editor1" basePath="ckeditor/" | ||
config="<%= ConfigurationHelper.createConfig() %>" | config="<%= ConfigurationHelper.createConfig() %>" |
Latest revision as of 09:06, 3 August 2011
Contents
System Requirements
Please note that you need at least JRE 1.4 and Servlet 2.5/JSP 2.1 to use the integration.
Installation
Adding CKEditor to your application is a two-step process that entails:
- downloading standalone CKEditor and placing it in the web application directory,
- 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
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-3.x.y*.jar
file, and put it in your /WEB-INF/lib
directory.
*
Please note that 3.x.y
denotes the version of a CKEditor release.
Using the Tag on the Page
To start using <ckeditor>
tags in your JSP page, you need to declare the CKEditor tag library inside it:
<%@ taglib uri="http://ckeditor.com" prefix="ckeditor" %>
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.
Replacing Selected 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.
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 HTMLtextarea
element that is to be replaced with a CKEditor instance. -
basePath
– contains the path to the main CKEditor directory.
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>
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.
Creating a CKEditor Instance
The <ckeditor:editor>
tag creates a CKEditor instance.
<ckeditor:editor textareaAttributes="<%=attr %>" basePath="/ckeditor/" 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
– contains the path to the main CKEditor directory. -
editor
– is the name of the internaltextarea
element. -
value
– is the defaulttextarea
element value. -
textareaAttributes
– is ajava.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"); %>
Common Tag Attributes
The list below presents some of the commonly used tag attributes.
basePath
basePath
– contains the path to the main CKEditor directory.
If, for example, CKEditor is available under http://example.com/3rdparty/ckeditor/
, the basePath
attribute should be set to /3rdparty/ckeditor/
.
config
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 settings = new CKEditorConfig(); settings.addConfigValue("width","500"); %> <ckeditor:replace replace="editor1" basePath="/ckeditor/" config="<%=settings %>" />
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 settings = new CKEditorConfig(); settings.addConfigValue("toolbar","[[ 'Source', '-', 'Bold', 'Italic' ]]"); %>
is equal to:
<% CKEditorConfig settings = 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); settings.addConfigValue("toolbar", list); %>
New CKEditor 3.6 Toolbar Syntax
As of CKEditor 3.6, toolbar buttons can be organized into groups. Each group has its own name and a set of buttons that it includes. The new definition can also be expressed in two ways.
The code below:
<% CKEditorConfig settings = new CKEditorConfig(); settings.addConfigValue("toolbar","[{name: 'document', items: ['Source', '-', 'NewPage']}, '/', {name: 'styles', items: ['Styles','Format']} ]"); %>
is equal to:
<% CKEditorConfig settings = new CKEditorConfig(); List<Object> mainList = new ArrayList<Object>(); HashMap<String, Object> toolbarSectionMap = new HashMap<String, Object>(); List<String> subList = new ArrayList<String>(); subList.add("Source"); subList.add("-"); subList.add("NewPage"); toolbarSectionMap.put("name", "document"); toolbarSectionMap.put("items", subList); mainList.add(toolbarSectionMap); mainList.add("/"); toolbarSectionMap = new HashMap<String, Object>(); subList = new ArrayList<String>(); subList.add("Styles"); subList.add("Format"); toolbarSectionMap.put("name", "styles"); toolbarSectionMap.put("items", subList); mainList.add(toolbarSectionMap); settings.addConfigValue("toolbar", mainList); %>
timestamp
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
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.
events
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
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); }"); %>
Setting configuration options in a Java class
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() %>" />