Integrating CKFinder

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.

(Change order of sections)
(File Upload Filter (Removed in CKFinder 2.6))
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{#CUSTOMTITLE:Integrating CKFinder}}__TOC__
+
__TOC__
 +
{{#CUSTOMTITLE:Integrating CKFinder}}
 
This article describes various ways of integrating CKFinder for Java with your page.
 
This article describes various ways of integrating CKFinder for Java with your page.
  
Line 8: Line 9:
 
* Copy the CKFinder <code>config.xml</code> file from its <code>WEB-INF</code> folder into the <code>WEB-INF</code> folder of your application.
 
* Copy the CKFinder <code>config.xml</code> file from its <code>WEB-INF</code> folder into the <code>WEB-INF</code> folder of your application.
 
* Copy the contents of the CKFinder <code>WEB-INF/lib</code> folder into the <code>WEB-INF/lib</code> folder of your application.
 
* Copy the contents of the CKFinder <code>WEB-INF/lib</code> folder into the <code>WEB-INF/lib</code> folder of your application.
* Copy the <code>ConnectorServlet</code> settings from the CKFinder <code>web.xml</code> file to the <code>web.xml</code> file of your application. Note that the <code><servlet-class></code> path and <code><url-pattern></code> will need to be adjusted to your application.
+
* Copy the <code>ConnectorServlet</code> settings from the CKFinder <code>web.xml</code> file to the <code>web.xml</code> file of your application.
 
<source lang="xml">
 
<source lang="xml">
 
<servlet>
 
<servlet>
Line 26: Line 27:
 
</servlet-mapping>  
 
</servlet-mapping>  
 
</source>
 
</source>
* Just like in the sample application, by default CKFinder is disabled due to security reasons. To turn it on, change the <code><enabled></code> element value in the <code>config.xml</code> file to <code>true</code>. Note that more sensitive authentication method by overriding the <code>checkAuthentication</code> method in recommended.
+
* Just like in the sample application, by default CKFinder is disabled due to security reasons. To turn it on, change the <code><enabled></code> element value in the <code>config.xml</code> file to <code>true</code>. Note that it is recommended to use a more fine-grained authentication method by overriding the <code>checkAuthentication</code> method.
 
<source lang="xml">
 
<source lang="xml">
 
<enabled>true</enabled>
 
<enabled>true</enabled>
 
</source>
 
</source>
 
* Similarily, some further adjustments of the <code>config.xml</code> file might be needed, like <code>baseUrl</code> and <code>baseDir</code> paths, for example.
 
* Similarily, some further adjustments of the <code>config.xml</code> file might be needed, like <code>baseUrl</code> and <code>baseDir</code> paths, for example.
 +
 +
==File Upload Filter (Removed in CKFinder 2.6)==
 +
 +
'''Note: the flash upload component has been completely removed in CKFinder 2.6. As a result, the FileUploadFilter is no longer included in CKFinder.'''
 +
 +
As described in the [[CKFinder_2.x/Developers_Guide/Java/Troubleshooting#Flash_Upload_Problem|Flash Upload Problem]] section of the Troubleshooting article, if you are using the Flash multiple file upload component together with session-based authentication, you might get some "missing cookies" problems when trying to upload files. To work around this Flash bug you have to take care of posting cookies yourself. On server side this is done by setting a <code>FileUploadFilter</code>:
 +
<source lang="xml">
 +
<filter>
 +
<filter-name>FileUploadFilter</filter-name>
 +
<filter-class>com.ckfinder.connector.FileUploadFilter</filter-class>
 +
        <init-param>
 +
              <param-name>sessionCookieName</param-name>
 +
              <param-value>JSESSIONID</param-value>
 +
        </init-param>
 +
        <init-param>
 +
              <param-name>sessionParameterName</param-name>
 +
              <param-value>jsessionid</param-value>
 +
        </init-param>
 +
</filter>
 +
<filter-mapping>
 +
<filter-name>FileUploadFilter</filter-name>
 +
<url-pattern>/ckfinder/core/connector/java/connector.java</url-pattern>
 +
</filter-mapping>
 +
</source>
 +
 +
Besides basic elements like name, full class declaration (<code><filter-class></code>), and a mapping applying the filter to a specific URL (it has to be the same mapping as for <code>ConnectorServlet</code>), there are also two optional configuration parameters which help to identify "authentication cookies" that need to be rewritten.
 +
 +
Those parameters are the name of the session cookie (<code>sessionCookieName</code>), which in Java defaults to the <code>JSESSIONID</code> value, and the name of the session path parameter (<code>sessionParameterName</code>), which in Java defaults to <code>jsessionid</code>. These parameters are optional and can be omitted. However, if you are using custom configuration and you have changed names for these session identifiers on your server, you should also specify them in the <code>FileUploadFilter</code> init parameters so that CKFinder would know what to rewrite.
  
 
== Installing CKFinder as a JSP Page Tag ==
 
== Installing CKFinder as a JSP Page Tag ==
 
In order to install CKFinder as a tag inside a <code>.jsp</code> page, follow the steps outlined below:
 
In order to install CKFinder as a tag inside a <code>.jsp</code> page, follow the steps outlined below:
 
* Install CKFinder as described in the section above.
 
* Install CKFinder as described in the section above.
* Copy the <code>ckfinder.tld</code> from the <code>WEB-INF</code> folder of CKFinder and paste it into the <code>WEB-INF</code> folder of your application.
 
* In the <code>web.xml</code> file of your application add the following entry:
 
<source lang="xml">
 
<jsp-config>
 
    <taglib>
 
          <taglib-uri>/WEB-INF/ckfinder</taglib-uri>
 
          <taglib-location>/WEB-INF/ckfinder.tld</taglib-location>
 
    </taglib>
 
</jsp-config>
 
</source>
 
 
* In order to use the tag on the JSP page you should import the tag library by using the following directive:
 
* In order to use the tag on the JSP page you should import the tag library by using the following directive:
 
<source lang="java">
 
<source lang="java">
<%@ taglib uri='../../WEB-INF/ckfinder.tld' prefix='ck' %>
+
<%@ taglib uri="http://cksource.com/ckfinder" prefix="ckfinder" %>
 
</source>
 
</source>
  
 
You can now use the CKFinder tag on your JSP page in the following way:
 
You can now use the CKFinder tag on your JSP page in the following way:
 
<source lang="java">
 
<source lang="java">
<ck:ckfinder basePath="/CKFinderJava-1.0/ckfinder/" />
+
<ckfinder:ckfinder basePath="/CKFinderJava/ckfinder/" />
 
</source>
 
</source>
  
Line 58: Line 77:
  
 
<source lang="java">
 
<source lang="java">
<ck:ckfinder basePath="/CKFinderJava-1.0/ckfinder/" width="700" height="500" />
+
<ckfinder:ckfinder basePath="/CKFinderJava/ckfinder/" width="700" height="500" />
 
</source>
 
</source>
  
Line 64: Line 83:
  
 
== Extending Configuration ==
 
== Extending Configuration ==
CKFinder implements some access control that is available from your application. You can create a class that inherits and extends the <code>Configuration</code> class. A sample code can be seen below:
+
To read more about extending your CKFinder configuration, refer to the [[CKFinder_2.x/Developers_Guide/Java/Configuration/Extending|Extending CKFinder Configuration]] article.
 
 
<source lang="java">
 
public class MyConfiguration extends Configuration {
 
  
public MyConfiguration(ServletConfig servletConfig) {
+
== Integration methods ==
super(servletConfig);
+
* [[/JavaScript|JavaScript integration]] &ndash; the preferred integration method, simple yet powerful.
}
 
 
 
@Override
 
public Boolean checkAuthentication() {
 
return false;
 
}
 
}
 
</source>
 
 
 
 
 
Special attention should be paid to the <code>checkAuthentication</code> method. It can be used to specify the pre-requisites (like administrator rights) that have to be met in order to make CKFinder available.
 
 
 
This option is obviously not the only one that you can control. You can override each of the <code>Configuration</code> class methods that represent CKFinder setting, including enabling and disabling CKFinder.
 
 
 
To make CKFinder aware of your custom configuration class, add the following to WEB-INF/web.xml:
 
<source lang="xml">
 
<init-param>
 
  <param-name>configuration</param-name>
 
  <param-value>com.ckfinder.connector.MyConfiguration</param-value>
 
</init-param>
 
</source>
 

Latest revision as of 19:20, 5 December 2015

This article describes various ways of integrating CKFinder for Java with your page.

Integrating CKFinder with your Application

After you download the CKFinder for Java .war file, follow the steps below to integrate it with your application:

  • Unpack CKFinder for Java.
  • Copy the ckfinder folder to your application.
  • Copy the CKFinder config.xml file from its WEB-INF folder into the WEB-INF folder of your application.
  • Copy the contents of the CKFinder WEB-INF/lib folder into the WEB-INF/lib folder of your application.
  • Copy the ConnectorServlet settings from the CKFinder web.xml file to the web.xml file of your application.
<servlet>
	<servlet-name>ConnectorServlet</servlet-name>
	<servlet-class>com.ckfinder.connector.ConnectorServlet</servlet-class>
	<init-param>
		<param-name>XMLConfig</param-name>
		<param-value>/WEB-INF/config.xml</param-value>
	</init-param>
	<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
	<servlet-name>ConnectorServlet</servlet-name>
	<url-pattern>
		/ckfinder/core/connector/java/connector.java
	</url-pattern>
</servlet-mapping>
  • Just like in the sample application, by default CKFinder is disabled due to security reasons. To turn it on, change the <enabled> element value in the config.xml file to true. Note that it is recommended to use a more fine-grained authentication method by overriding the checkAuthentication method.
<enabled>true</enabled>
  • Similarily, some further adjustments of the config.xml file might be needed, like baseUrl and baseDir paths, for example.

File Upload Filter (Removed in CKFinder 2.6)

Note: the flash upload component has been completely removed in CKFinder 2.6. As a result, the FileUploadFilter is no longer included in CKFinder.

As described in the Flash Upload Problem section of the Troubleshooting article, if you are using the Flash multiple file upload component together with session-based authentication, you might get some "missing cookies" problems when trying to upload files. To work around this Flash bug you have to take care of posting cookies yourself. On server side this is done by setting a FileUploadFilter:

<filter>
	<filter-name>FileUploadFilter</filter-name>
	<filter-class>com.ckfinder.connector.FileUploadFilter</filter-class>
        <init-param>
              <param-name>sessionCookieName</param-name>
              <param-value>JSESSIONID</param-value>
        </init-param>
        <init-param>
              <param-name>sessionParameterName</param-name>
              <param-value>jsessionid</param-value>
        </init-param>
</filter>
<filter-mapping>
	<filter-name>FileUploadFilter</filter-name>
	<url-pattern>/ckfinder/core/connector/java/connector.java</url-pattern>
</filter-mapping>

Besides basic elements like name, full class declaration (<filter-class>), and a mapping applying the filter to a specific URL (it has to be the same mapping as for ConnectorServlet), there are also two optional configuration parameters which help to identify "authentication cookies" that need to be rewritten.

Those parameters are the name of the session cookie (sessionCookieName), which in Java defaults to the JSESSIONID value, and the name of the session path parameter (sessionParameterName), which in Java defaults to jsessionid. These parameters are optional and can be omitted. However, if you are using custom configuration and you have changed names for these session identifiers on your server, you should also specify them in the FileUploadFilter init parameters so that CKFinder would know what to rewrite.

Installing CKFinder as a JSP Page Tag

In order to install CKFinder as a tag inside a .jsp page, follow the steps outlined below:

  • Install CKFinder as described in the section above.
  • In order to use the tag on the JSP page you should import the tag library by using the following directive:
<%@ taglib uri="http://cksource.com/ckfinder" prefix="ckfinder" %>

You can now use the CKFinder tag on your JSP page in the following way:

<ckfinder:ckfinder basePath="/CKFinderJava/ckfinder/" />

The only required attribute is the basePath that specifies the path to the CKFinder folder. Numerous optional attributes are also available and can be used to customize CKFinder to your needs, like in the example below:

<ckfinder:ckfinder basePath="/CKFinderJava/ckfinder/" width="700" height="500" />

This code creates a CKFinder instance with a width of 700 pixels and height of 500 pixels.

Extending Configuration

To read more about extending your CKFinder configuration, refer to the Extending CKFinder Configuration article.

Integration methods

This page was last edited on 5 December 2015, at 19:20.