Latest revision as of 20:34, 2 May 2011

The MyConfiguration class lets you change the base CKFinder configuration, or, in other words, change the settings from the XML file at the Java class level.

To make CKFinder aware of the new configuration settings it is necessary to add the following entry to the web.xml file.

<init-param>
	<param-name>configuration</param-name>
	<param-value>com.ckfinder.connector.configuration.MyConfiguration</param-value>
</init-param>

This entry assumes that your MyConfiguration class was created in the com.ckfinder.connector.configuration package.

The basic structure of a class that extends CKFinder configuration looks like this:

public class MyConfiguration extends Configuration {


        public MyConfiguration(ServletConfig servletConfig) {
		super(servletConfig);
	}	

        
        @Override
	protected Configuration createConfigurationInstance() {
		return new MyConfiguration(this.servletConf);
	}
}

Based on the above template, two important things should be noted.

First of all, at least theoretically you can avoid overriding the createConfigurationInstance method, but in this case almost none of the changes introduced in MyConfiguration class will have any effect. The only exception to this is the init method, where the changes will be visible, because it operates directly on the class fields. This technique is not recommended and was only mentioned for clarification purposes. This article assumes that you have extended the createConfigurationInstance method as described.

Secondly, at the moment the class uses the base configuration. In order to introduce custom settings you need to extend the Configuration class methods, like init, checkAuthentication, prepareConfigurationForRequest, and specific getter methods. For examples on extending some of these methods check the section below.

Changing Configuration in the init Method

This section describes how to override the whole XML file based configuration or just a part of it.

The first operation in the init method should be to call the init method of the base class by using the following instruction:

super.init();

This instruction will read the configuration from the XML file. If you want to create your own configuration from scratch, without reading the default one from the XML file, this step can omitted.

The example below shows how to modify the path for the baseURL setting and add the zip and 7z extensions to allowedExtensions. It is assumed that the Files resource type was added to the default configuration.

@Override
public void init() throws Exception {
	super.init();
	this.baseURL = "/CKFinderJava/userfiles/";
	ResourceType resourceType = this.types.get("Files");
	resourceType.setAllowedExtensions(
		resourceType.getAllowedExtensions().concat(",zip,7z"));   
}

Extending the checkAuthentication Method

CKFinder implements some access control that is available from your application. You can create a class that inherits and extends the Configuration class with your custom checkAuthentication 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 method allows you to run your own checks to see whether the user should have access to CKFinder. The checks are executed on the application level.

The example below checks whether the user is logged into the application by testing the session attribute named loggedIn.

@Override
public boolean checkAuthentication(final HttpServletRequest request) {
	return request.getSession().getAttribute("loggedIn") != null;
}

Extending the Access Method for a Specific Configuration Class Field

Any value defined in the XML tags, like <licenseName>sampleLicenseName</licenseName>, can be overridden in the MyConfiguration class.

The example below shows how to define the license name at the class level.

@Override
public String getLicenseName() {
	return "MyLicenseName";
}

Modifying the baseDir and baseURL Values

These two parameters deserve special attention since they are crucial for CKFinder configuration and at the same time can be modified in a few different ways.

For an explanation of the role of baseDir and baseURL parameters refer to the Quick Start guide article.

The baseDir and baseURL parameters can be configured by using the following methods described below.

Overriding the getBaseDir and getBaseURL Methods

Use the following code to override the getBaseDir and getBaseURL methods.

@Override
public String getBaseDir() {
	return "C:\\tomcat\\webapps\\MyApplication\\userfiles";
}

@Override
public String getBaseURL() {
	return "/MyApplication/userfiles/";
}

Setting the baseDir or baseURL Value in the init Method

Use the following code to set the baseDir and baseURL values directly in the init() method:

this.baseURL = "/MyApplication/userfiles/";

Creating a Custom PathBuilder Class

This approach requires you to create a class that implements the following interface:

com.ckfinder.connector.configuration.IBasePathBuilder

or extend an existing class that already implements this interface.

The following CKFinder classes already implement this interface:

• com.ckfinder.connector.configuration.DefaultPathBuilder

  This class creates a baseURL in the following form

  /application name/userfiles (e.g. /CKFinderJava/userfiles) and a baseDir in the form of an absolute path to the userfiles directory.

• com.ckfinder.connector.configuration.ConfigurationPathBuilder

  This class gets the values from the Configuration class object or, if available, from the object of a class that inherits from the Configuration class.

When creating a class that extends the DefaultPathBuilder class it is necessary to implement the getBaseDir and getBaseURL methods. These methods must not return empty values.

When the class is ready, the basePathBuilderImpl value should be set in the config.xml file.

<basePathBuilderImpl>my.sample.NewPathBuilder</basePathBuilderImpl>

The example below shows a new class named NewPathBuilder located in the my.sample package.

package my.sample;

import javax.servlet.http.HttpServletRequest;

import com.ckfinder.connector.configuration.DefaultPathBuilder;

public class NewPathBuilder extends DefaultPathBuilder {
	
	@Override
	public String getBaseDir(HttpServletRequest arg0) {
		return "C:\\tomcat\\webapps\\MyApplication\\myFiles";
	}
	
	@Override
	public String getBaseURL(HttpServletRequest request) {
		return "/MyApplication/myFiles/";
	}
}

With the above configuration CKFinder will use the myFiles directory as the main user files container instead of using the default userfiles directory.

The baseDir and baseURL parameters should not be modified in the prepareConfigurationForRequest method as this will cause the changes to be ignored.

Changing the Configuration in the prepareConfigurationForRequest Method

While extending the prepareConfigurationForRequest method it is not necessary to call the base class method as it is empty.

The example below shows how to change the maximum image size based on its resource type. For the Images resource type the maximum dimensions will be set for 800x600 pixels, while for the Files type the size will be set to 600x480 pixels.

The code below also shows how to change the direct access to thumbnails by calling an additional parameter in the request.

@Override
public void prepareConfigurationForRequest(HttpServletRequest  request) {
	if (request.getParameter("directThumbAccess") != null) {
		this.thumbsDirectAccess = true;
	}
	String type = request.getParameter("type");		
	if ("Files".equals(type)) {
		this.imgHeight = 480;
		this.imgWidth = 600;
	}
	if ("Images".equals(type)) {
		this.imgWidth = 800;
		this.imgHeight = 600;
	}
	this.baseURL = "/webapps/ckfinder/";	//This will not work!
	this.baseDir = "c:\ckfinder";		//This will not work!
}

Additionally, this example also contains some code that attempts to modify the baseDir and baseURL parameters. As mentioned above, this change will have no effect and will be ignored.