Upgrading

Table of Contents

• Upgrading CKFinder 3.x
• Upgrading from CKFinder 2.x to 3.x
  • Changes in CKFinder 3.x
  • Upgrading
  • Configuration Options Migration - ASP.NET Settings

Latest CKFinder is always the greatest CKFinder. Each new release brings plenty of bug fixes and new features, so it is highly recommended to upgrade often.

Upgrading CKFinder 3.x

1. Download the latest CKFinder version from the official CKFinder website.
2. Backup your old copy of CKFinder to a safe place.
3. Temporarily disable access to CKFinder for all users of your application.
4. Delete all files from the CKFinder folder (remember to not delete the userfiles folder if you configured CKFinder to store files there).
5. Unpack the new CKFinder version to the folder where old CKFinder was previously installed.
6. Apply changes from the old configuration file to the new configuration file shipped with CKFinder (most of the time, you can simply use the old configuration file).
7. (Optional) In your application add a timestamp to the path to ckfinder.js to help browsers recognize that the new version of the file is available, e.g.:

    <script type="text/javascript" src="/ckfinder/ckfinder.js?t=20100601"></script>

8. Perform some simple tests to ensure that CKFinder is running fine.
9. Enable access to CKFinder for all users of your application.

Upgrading from CKFinder 2.x to 3.x

Changes in CKFinder 3.x

Although some configuration options in CKFinder 3.x look familiar, its configuration and API are incompatible with previous versions of CKFinder.

CKFinder 3.x comes wth many new features, but at the same time it misses a couple of features available in CKFinder 2.x:

• The Zip/Unzip plugin.
• The "File Edit" feature for editing text files.

These features may be added in the future CKFinder releases.

CKFinder 3.x also dropped support for Internet Explorer 8 and is no longer shipped with the Flash component for file uploads, which sometimes required really tricky workarounds due to Flash bugs with handling cookies. In CKFinder 3.x HTML5 features are exclusively used for multiple file uploads — the fallback in older browsers is that users can only select one file.

Upgrading

1. Download the latest CKFinder version from the official CKFinder website.
2. Backup your old copy of CKFinder to a safe place.
3. Temporarily disable access to CKFinder for all users of your application.
4. Delete all files from the CKFinder folder (remember to not delete the userfiles folder if you configured CKFinder to store files there).
5. Unpack the new CKFinder version to the folder where old CKFinder was previously installed.
6. Manually apply changes from the old configuration file to the new configuration file shipped with CKFinder (you cannot use the old configuration file).
7. (Optional) In your application add a timestamp to the path to ckfinder.js to help browsers recognize that the new version of the file is available, e.g.:

    <script type="text/javascript" src="/ckfinder/ckfinder.js?t=20100601"></script>

8. To integrate CKFinder with your application you need to attach the main CKFinder JavaScript file to the page, like shown above. To start the application on a page as a widget, add the following HTML container where CKFinder will be rendered:

    <div id="ckfinder1"></div>

   and then add the JavaScript code to the document to insert CKFinder into that container:

   <script>
       CKFinder.widget( 'ckfinder1', {
           width: 960,
           height: 700,
       } );
   </script>

   Please refer to CKFinder Quick Start Guide to find more information about integrating CKFinder with your website.

   Note: The plugins from version 2.x are not compatible with version 3.x. If you created any custom plugins, they need to be rewritten. To check what custom changes you made in the past in your own copy of CKFinder 2.x, you can download a fresh copy from http://cksource.com/ckfinder and compare both versions using a diff tool (for example WinMerge).

9. Perform some simple tests to ensure that CKFinder is running fine.
10. Enable access to CKFinder for all users of your application.

Configuration Options Migration - ASP.NET Settings

The following table sums up the differences between the server-side side configuration options available in CKFinder 2 and CKFinder 3.

CKFinder 2.x	CKFinder 3.x (configuration file)	CKFinder 3.x (ConnectorBuilder and ConnectorConfiguration)	Notes
AccessControl	<accessControl />	AddAclRule	-
-	<backends />	AddBackend AddProxyBackend	New in CKFinder 3.x.
CheckDoubleExtension	<ckfinder />	SetCheckDoubleExtension	-
CheckSizeAfterScaling	<ckfinder />	SetCheckSizeAfterScaling	-
DefaultResourceTypes	-	-	Multiple resources are supported.
DisallowUnsafeCharacters	<ckfinder />	SetDisallowUnsafeCharacters	-
HideFolders	<hideFolders />	SetHideFoldersMatchers	-
HideFiles	<hideFiles />	SetHideFilesMatchers	-
HtmlExtensions	<htmlExtensions />	SetAllowedHtmlExtensionMatchers	-
Images	<images />	SetMaxImageSize SetDefaultImageQuality SetSizeDefinitions	-
LicenseName	<license />	SetLicense	-
LicenseKey	<license />	SetLicense	-
-	<ckfinder />	SetOverwriteOnUpload	New in CKFinder 3.x.
-	<plugins />	SetPluginsPath AddPlugin	New in CKFinder 3.x.
ResourceType	<resources />	AddResourceType	-
SecureImageUploads	<ckfinder />	SetSecureImageUploads	-
Thumbnails	<thumbnails />	SetThumbnailSizes SetThumbnailBackend	-

Refer to the Configuration Options Migration - JavaScript Settings section for a list of changes in the client-side options (defined in config.js or passed inline when creating CKFinder instances).