A Small History
CKEditor has been one of the most popular and used WYSIWYG editor for web, which has been used by many popular open source projects, websites and companies. According to its official website, FCKeditor has been around for more than six years. Since 2003 it has built a strong user community becoming the most used editor in the market, accumulating more than 3,5 million downloads. On 2009, the company decided renaming the editor, bringing to the light their next generation solution: CKEditor 3.0.
CKEditor inherits the quality and strong features people were used to find in FCKeditor, in a much more modern product, added by dozens of new benefits, like accessibility and ultimate performance.CKEditor has made many features pluggable so that it can be extended by developers according to their needs.
Why this tutorial?
However, the new CKEditor does not provide the File Manager/File Browser that it used to provide by default in FCKEditor. This functionality is now provided by CKFinder. CKFinder provides many cool functions and is definitely a better product than traditional FCKEditor’s FIle Browser, but its not a free product and users have to purchase the license in order to use the product.
If you are not willing to purchase CKFinder you can make your own external file manager and plugin to CKEditor through its APIs, alternatively you can directly integrate the FCKEditor’s File Manager (File Browser) feature with CKEditor. This is what i am going to describe in this short tutorial.
Before starting the tutorial you may also like to view the fully functional demo, or you may download the example and start working on it. Please note that this tutorial is for the PHP language and connectors, but same steps can also be applied for other supported languages and connectors.
Also I assume that you have sufficient knowledge about integrating CKEditor on your page.
Starting with the tutorial
Download the CKEditor and copy it to your desired folder. In this example I have copied it to
siteroot/filemanager_in_ckeditor/js/ckeditor |
siteroot/filemanager_in_ckeditor/js/ckeditor
demo.html is the page where I would like to add the WYSIWYG editor, and I have placed my page over here:
siteroot/filemanager_in_ckeditor/demo.html |
siteroot/filemanager_in_ckeditor/demo.html
Since we are going to integrate the inbuilt File Manager available in FCKEditor we will copy the ‘filemanager’ folder from the FCKEditor source files which is genereally located in
In this example I have copied the ‘filemanager’ folder to
siteroot/filemanager_in_ckeditor/js/ckeditor/ |
siteroot/filemanager_in_ckeditor/js/ckeditor/
At this stage you may delete the connectors from the filemanager folder which you are not using. I have deleted all the connector folders except the ‘php’ connector which I am using in this example.
Once the required files are copied you need to tie up the filemanager with CKEditor and make it active in the code. To do this you need to modify the CKEditor intialization code like below. (Obviously this goes in demo.html page in my case)
CKEDITOR.replace( 'editor1',
{
filebrowserBrowseUrl :'js/ckeditor/filemanager/browser/default/browser.html?Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserImageBrowseUrl : 'js/ckeditor/filemanager/browser/default/browser.html?Type=Image&Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserFlashBrowseUrl :'js/ckeditor/filemanager/browser/default/browser.html?Type=Flash&Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php'}
); |
CKEDITOR.replace( 'editor1',
{
filebrowserBrowseUrl :'js/ckeditor/filemanager/browser/default/browser.html?Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserImageBrowseUrl : 'js/ckeditor/filemanager/browser/default/browser.html?Type=Image&Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserFlashBrowseUrl :'js/ckeditor/filemanager/browser/default/browser.html?Type=Flash&Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php'}
);
The above options, enables the “Browse Server” buttons on the “Link”, “Image”, “Flash” dialogs. You will have to adjust the above paths according to your directory structure. Also please note that for the sake of simplicity I have hard coded my website domain (www.mixedwaves.com) in the above paths, this should be changed to whatever is applicable in your case and can be added dynamically instead of hard coding it.
One important thing to remember at this stage is that while integrating the File Browser in CKEditor we still have to make configuration changes that we used to do for enabling the Browse and Upload functions in FCKEditor. Like enabling the php connector and specifying the UserFilesPath to correct location in:
filemanager/connectors/php/config.php |
filemanager/connectors/php/config.php
Up to now if everything has gone correct, you should be able to see the “Browse Server” buttons in the “Link”, “Image” and “Flash” dialogs. Clicking on the “Browse Server” button would open the “File Manager” window.
As a last step to making everything work you need to modify the following file:
filemanager/browser/default/frmresourcelist.html |
filemanager/browser/default/frmresourcelist.html
You need to add the following JavaScript function, where all the other Javascript functions have been defined. Copy and paste the below code:
function GetUrlParam( paramName )
{
var oRegex = new RegExp( '[\?&]' + paramName + '=([^&]+)', 'i' ) ;
var oMatch = oRegex.exec( window.top.location.search ) ;
if ( oMatch && oMatch.length > 1 )
return decodeURIComponent( oMatch[1] ) ;
else
return '' ;
} |
function GetUrlParam( paramName )
{
var oRegex = new RegExp( '[\?&]' + paramName + '=([^&]+)', 'i' ) ;
var oMatch = oRegex.exec( window.top.location.search ) ;
if ( oMatch && oMatch.length > 1 )
return decodeURIComponent( oMatch[1] ) ;
else
return '' ;
}
In the same file you need to modify the function called “OpenFile”. Search the function “OpenFile” and replace it with the following function:
Update: 25 June 2011
File names with spaces are now visible in preview window. Earlier filenames with spaces were not encoded correctly hence were not visible in preview window. Thanks to Angela Yamat and Len
function OpenFile( fileUrl )
{
//PATCH: Using CKEditors API we set the file in preview window.
funcNum = GetUrlParam('CKEditorFuncNum') ;
//fixed the issue: images are not displayed in preview window when filename contain spaces due encodeURI encoding already encoded fileUrl
window.top.opener.CKEDITOR.tools.callFunction( funcNum, fileUrl);
///////////////////////////////////
window.top.close() ;
window.top.opener.focus() ;
} |
function OpenFile( fileUrl )
{
//PATCH: Using CKEditors API we set the file in preview window.
funcNum = GetUrlParam('CKEditorFuncNum') ;
//fixed the issue: images are not displayed in preview window when filename contain spaces due encodeURI encoding already encoded fileUrl
window.top.opener.CKEDITOR.tools.callFunction( funcNum, fileUrl);
///////////////////////////////////
window.top.close() ;
window.top.opener.focus() ;
}
The above code essentially sets the file URL to the preview window in the dialog box, when user selects a file in the File Manager.
With this you are done integrating the File Manager in CKEditor.
If everything has been configured and patched correctly, you should now be able to use a fully functional File Browser window just like you used to do in old FCKEditor.
Update: 3rd April 2010
With the generous effort of Brombomb, you can now also enable the ‘Upload’ tab for quick upload of files in your File Browser. You can find the hack on this link: http://stackoverflow.com/questions/1903510/ckeditor-integration-with-fckeditor-filebrowser/2564039
I have also implemented the above solution but with few modifications and in more systematic way so that the functionality is as close as possible with the old FCKEditor file browser. Thanks again to Brombomb.
Continuing with the tutorial, Enabling Quick Upload
Once you are done with the above steps you will have fairly working File Browser Window. However the old FCKEditor also supported a feature called Quick Upload and had separate upload tab. The upload tab can be enabled and made functional by following the below four steps.
In your CKEditor initialization code you need to add few more config variables as shown below that enables the Quick Upload tab. (Again this goes in demo.html page)
CKEDITOR.replace( 'editor1',
{
filebrowserBrowseUrl :'js/ckeditor/filemanager/browser/default/browser.html?Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserImageBrowseUrl : 'js/ckeditor/filemanager/browser/default/browser.html?Type=Image&Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserFlashBrowseUrl :'js/ckeditor/filemanager/browser/default/browser.html?Type=Flash&Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserUploadUrl :'http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/upload.php?Type=File',
filebrowserImageUploadUrl : 'http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/upload.php?Type=Image',
filebrowserFlashUploadUrl : 'http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/upload.php?Type=Flash'
}); |
CKEDITOR.replace( 'editor1',
{
filebrowserBrowseUrl :'js/ckeditor/filemanager/browser/default/browser.html?Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserImageBrowseUrl : 'js/ckeditor/filemanager/browser/default/browser.html?Type=Image&Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserFlashBrowseUrl :'js/ckeditor/filemanager/browser/default/browser.html?Type=Flash&Connector=http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/connector.php',
filebrowserUploadUrl :'http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/upload.php?Type=File',
filebrowserImageUploadUrl : 'http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/upload.php?Type=Image',
filebrowserFlashUploadUrl : 'http://www.mixedwaves.com/filemanager_in_ckeditor/js/ckeditor/filemanager/connectors/php/upload.php?Type=Flash'
});
Again need not mention, that the domain needs to be replaced by your own domain. The last three config variables in the above code enables the “Upload” tab in your “Flash”, “Image”, “File” dialogs. Same can be done for “Media” type which I haven’t done in this tutorial.
Now in next few steps we are going to modify/hack few files, this needs little care and attention.
Open the the file
filemanager/connectors/php/upload.php |
filemanager/connectors/php/upload.php
And search and replace the PHP function call “FileUpload” with the following code snippet
// Get the CKEditor Callback
$CKEcallback = $_GET['CKEditorFuncNum'];
//pass it on to file upload function
FileUpload( $sType, $sCurrentFolder, $sCommand, $CKEcallback ); |
// Get the CKEditor Callback
$CKEcallback = $_GET['CKEditorFuncNum'];
//pass it on to file upload function
FileUpload( $sType, $sCurrentFolder, $sCommand, $CKEcallback );
Now open the below file and search for the function definition “FileUpload”.
filemanager/connectors/php/commands.php |
filemanager/connectors/php/commands.php
Here we are going to add a new parameter to the function parameter list, as well as some modification in the body of the function. I would recommend you to replace the entire function definition with the following new function definition
// Notice the last paramter added to pass the CKEditor callback function
function FileUpload( $resourceType, $currentFolder, $sCommand, $CKEcallback = '' )
{
if (!isset($_FILES)) {
global $_FILES;
}
$sErrorNumber = '0' ;
$sFileName = '' ;
//PATCH to detect a quick file upload.
if (( isset( $_FILES['NewFile'] ) && !is_null( $_FILES['NewFile']['tmp_name'] ) ) || (isset( $_FILES['upload'] ) && !is_null( $_FILES['upload']['tmp_name'] ) ))
{
global $Config ;
//PATCH to detect a quick file upload.
$oFile = isset($_FILES['NewFile']) ? $_FILES['NewFile'] : $_FILES['upload'];
// Map the virtual path to the local server path.
$sServerDir = ServerMapFolder( $resourceType, $currentFolder, $sCommand ) ;
// Get the uploaded file name.
$sFileName = $oFile['name'] ;
$sFileName = SanitizeFileName( $sFileName ) ;
$sOriginalFileName = $sFileName ;
// Get the extension.
$sExtension = substr( $sFileName, ( strrpos($sFileName, '.') + 1 ) ) ;
$sExtension = strtolower( $sExtension ) ;
if ( isset( $Config['SecureImageUploads'] ) )
{
if ( ( $isImageValid = IsImageValid( $oFile['tmp_name'], $sExtension ) ) === false )
{
$sErrorNumber = '202' ;
}
}
if ( isset( $Config['HtmlExtensions'] ) )
{
if ( !IsHtmlExtension( $sExtension, $Config['HtmlExtensions'] ) &&
( $detectHtml = DetectHtml( $oFile['tmp_name'] ) ) === true )
{
$sErrorNumber = '202' ;
}
}
// Check if it is an allowed extension.
if ( !$sErrorNumber && IsAllowedExt( $sExtension, $resourceType ) )
{
$iCounter = 0 ;
while ( true )
{
$sFilePath = $sServerDir . $sFileName ;
if ( is_file( $sFilePath ) )
{
$iCounter++ ;
$sFileName = RemoveExtension( $sOriginalFileName ) . '(' . $iCounter . ').' . $sExtension ;
$sErrorNumber = '201' ;
}
else
{
move_uploaded_file( $oFile['tmp_name'], $sFilePath ) ;
if ( is_file( $sFilePath ) )
{
if ( isset( $Config['ChmodOnUpload'] ) && !$Config['ChmodOnUpload'] )
{
break ;
}
$permissions = 0777;
if ( isset( $Config['ChmodOnUpload'] ) && $Config['ChmodOnUpload'] )
{
$permissions = $Config['ChmodOnUpload'] ;
}
$oldumask = umask(0) ;
chmod( $sFilePath, $permissions ) ;
umask( $oldumask ) ;
}
break ;
}
}
if ( file_exists( $sFilePath ) )
{
//previous checks failed, try once again
if ( isset( $isImageValid ) && $isImageValid === -1 && IsImageValid( $sFilePath, $sExtension ) === false )
{
@unlink( $sFilePath ) ;
$sErrorNumber = '202' ;
}
else if ( isset( $detectHtml ) && $detectHtml === -1 && DetectHtml( $sFilePath ) === true )
{
@unlink( $sFilePath ) ;
$sErrorNumber = '202' ;
}
}
}
else
$sErrorNumber = '202' ;
}
else
$sErrorNumber = '202' ;
$sFileUrl = CombinePaths( GetResourceTypePath( $resourceType, $sCommand ) , $currentFolder ) ;
$sFileUrl = CombinePaths( $sFileUrl, $sFileName ) ;
if($CKEcallback == '')
{
SendUploadResults( $sErrorNumber, $sFileUrl, $sFileName ) ;
}
else
{
//issue the CKEditor Callback
SendCKEditorResults ($sErrorNumber, $CKEcallback, $sFileUrl, $sFileName);
}
exit ;
} |
// Notice the last paramter added to pass the CKEditor callback function
function FileUpload( $resourceType, $currentFolder, $sCommand, $CKEcallback = '' )
{
if (!isset($_FILES)) {
global $_FILES;
}
$sErrorNumber = '0' ;
$sFileName = '' ;
//PATCH to detect a quick file upload.
if (( isset( $_FILES['NewFile'] ) && !is_null( $_FILES['NewFile']['tmp_name'] ) ) || (isset( $_FILES['upload'] ) && !is_null( $_FILES['upload']['tmp_name'] ) ))
{
global $Config ;
//PATCH to detect a quick file upload.
$oFile = isset($_FILES['NewFile']) ? $_FILES['NewFile'] : $_FILES['upload'];
// Map the virtual path to the local server path.
$sServerDir = ServerMapFolder( $resourceType, $currentFolder, $sCommand ) ;
// Get the uploaded file name.
$sFileName = $oFile['name'] ;
$sFileName = SanitizeFileName( $sFileName ) ;
$sOriginalFileName = $sFileName ;
// Get the extension.
$sExtension = substr( $sFileName, ( strrpos($sFileName, '.') + 1 ) ) ;
$sExtension = strtolower( $sExtension ) ;
if ( isset( $Config['SecureImageUploads'] ) )
{
if ( ( $isImageValid = IsImageValid( $oFile['tmp_name'], $sExtension ) ) === false )
{
$sErrorNumber = '202' ;
}
}
if ( isset( $Config['HtmlExtensions'] ) )
{
if ( !IsHtmlExtension( $sExtension, $Config['HtmlExtensions'] ) &&
( $detectHtml = DetectHtml( $oFile['tmp_name'] ) ) === true )
{
$sErrorNumber = '202' ;
}
}
// Check if it is an allowed extension.
if ( !$sErrorNumber && IsAllowedExt( $sExtension, $resourceType ) )
{
$iCounter = 0 ;
while ( true )
{
$sFilePath = $sServerDir . $sFileName ;
if ( is_file( $sFilePath ) )
{
$iCounter++ ;
$sFileName = RemoveExtension( $sOriginalFileName ) . '(' . $iCounter . ').' . $sExtension ;
$sErrorNumber = '201' ;
}
else
{
move_uploaded_file( $oFile['tmp_name'], $sFilePath ) ;
if ( is_file( $sFilePath ) )
{
if ( isset( $Config['ChmodOnUpload'] ) && !$Config['ChmodOnUpload'] )
{
break ;
}
$permissions = 0777;
if ( isset( $Config['ChmodOnUpload'] ) && $Config['ChmodOnUpload'] )
{
$permissions = $Config['ChmodOnUpload'] ;
}
$oldumask = umask(0) ;
chmod( $sFilePath, $permissions ) ;
umask( $oldumask ) ;
}
break ;
}
}
if ( file_exists( $sFilePath ) )
{
//previous checks failed, try once again
if ( isset( $isImageValid ) && $isImageValid === -1 && IsImageValid( $sFilePath, $sExtension ) === false )
{
@unlink( $sFilePath ) ;
$sErrorNumber = '202' ;
}
else if ( isset( $detectHtml ) && $detectHtml === -1 && DetectHtml( $sFilePath ) === true )
{
@unlink( $sFilePath ) ;
$sErrorNumber = '202' ;
}
}
}
else
$sErrorNumber = '202' ;
}
else
$sErrorNumber = '202' ;
$sFileUrl = CombinePaths( GetResourceTypePath( $resourceType, $sCommand ) , $currentFolder ) ;
$sFileUrl = CombinePaths( $sFileUrl, $sFileName ) ;
if($CKEcallback == '')
{
SendUploadResults( $sErrorNumber, $sFileUrl, $sFileName ) ;
}
else
{
//issue the CKEditor Callback
SendCKEditorResults ($sErrorNumber, $CKEcallback, $sFileUrl, $sFileName);
}
exit ;
}
As a final step, we are going to modify the below file and add a new function towards the end of the file
filemanager/connectors/php/io.php |
filemanager/connectors/php/io.php
Add the below function towards the end of the file
// This is the function that sends the results of the uploading process to CKEditor.
function SendCKEditorResults ($errorNumber, $CKECallback, $fileUrl, $fileName, $customMsg ='')
{
// Minified version of the document.domain automatic fix script (#1919).
// The original script can be found at _dev/domain_fix_template.js
echo <<<EOF
<script type="text/javascript">
(function(){var d=document.domain;while (true){try{var A=window.parent.document.domain;break;}catch(e) {};d=d.replace(/.*?(?:\.|$)/,'');if (d.length==0) break;try{document.domain=d;}catch (e){break;}}})();
EOF;
if ($errorNumber && $errorNumber != 201) {
$fileUrl = "";
$fileName= "";
}
$msg = "";
switch ($errorNumber )
{
case 0 :
$msg = "Upload successful";
break;
case 1 : // Custom error.
$msg = $customMsg;
break ;
case 201 :
$msg = 'A file with the same name is already available. The uploaded file has been renamed to "' . $fileName . '"' ;
break ;
case 202 :
$msg = 'Invalid file' ;
break ;
default :
$msg = 'Error on file upload. Error number: ' + $errorNumber ;
break ;
}
$rpl = array( '\\' => '\\\\', '"' => '\\"' ) ;
echo 'window.parent.CKEDITOR.tools.callFunction("'. $CKECallback. '","'. strtr($fileUrl, $rpl). '", "'. strtr( $msg, $rpl). '");' ;
echo '</script>';
} |
// This is the function that sends the results of the uploading process to CKEditor.
function SendCKEditorResults ($errorNumber, $CKECallback, $fileUrl, $fileName, $customMsg ='')
{
// Minified version of the document.domain automatic fix script (#1919).
// The original script can be found at _dev/domain_fix_template.js
echo <<<EOF
<script type="text/javascript">
(function(){var d=document.domain;while (true){try{var A=window.parent.document.domain;break;}catch(e) {};d=d.replace(/.*?(?:\.|$)/,'');if (d.length==0) break;try{document.domain=d;}catch (e){break;}}})();
EOF;
if ($errorNumber && $errorNumber != 201) {
$fileUrl = "";
$fileName= "";
}
$msg = "";
switch ($errorNumber )
{
case 0 :
$msg = "Upload successful";
break;
case 1 : // Custom error.
$msg = $customMsg;
break ;
case 201 :
$msg = 'A file with the same name is already available. The uploaded file has been renamed to "' . $fileName . '"' ;
break ;
case 202 :
$msg = 'Invalid file' ;
break ;
default :
$msg = 'Error on file upload. Error number: ' + $errorNumber ;
break ;
}
$rpl = array( '\\' => '\\\\', '"' => '\\"' ) ;
echo 'window.parent.CKEDITOR.tools.callFunction("'. $CKECallback. '","'. strtr($fileUrl, $rpl). '", "'. strtr( $msg, $rpl). '");' ;
echo '</script>';
}
The above function essentially sends back the result of the upload to the preview window. It will alert if something wrong has happened like uploaded an invalid file.
With this we are done with integrating a full featured File Browser in CKEditor.
I hope this tutorial is useful to you. Please post your doubts or questions you may have and I would be happy to respond to it.
PS. I have taken utmost care to place the above code snippets correctly, however my WYSIWYG editor seems to change the PHP and JS code undesirably. If you find any errors/typos in the above code snippets you can check the actual source code files; it would be really great if you can bring it to my notice so that I can correct it and also help you out if possible.