2009/12/07

Using your own Uploader in CKEditor

CKEditor still doesn't include its own file manager, but the hooks to integrate your own uploader script or file manager are already in place, as you can check win CKFinder or any number of third party scripts that people have been writing.

Upgrading from FCKeditor

Maybe you want to use a previous uploader that you've used in FCKeditor and you are not sure about what are the differences, and the current documentation isn't clear enough for you. I'm pointing here the differences for the upload (or "quick upload") part, I might try to cover the slight differences in the "File browser" in other post.

  1. The file is sent as "upload" instead of "NewFile". Note that this is the value that you'll get using the default dialogs, but the name of the input is the id applied to the uiElement used to create the widget so in some situations you might get a different name.
  2. Some additional info is sent along the request as GET parameters: the name of the CKEditor instance, the current language code and a parameter to specify the callback function.
  3. The callback function is dynamic, you must read the "CKEditorFuncNum" parameter and send it back.
  4. There are no special error numbers in the callback function. Your script can return a url to use and a message to show to the user, both are optional so you can return just an URL that will be used in the dialog, or you can return a message that will be shown to the user, or a URL and a message (for example a warning that the file has been renamed and the new URL).
  5. Thanks to the message and the "langCode" parameter you can use localized messages instead of having them in English.

So I think that that is the summary of differences showing that the limitations in the previous API (hardcoded error numbers and messages, no info about the current instance...) have been fixed.

Practical example

Maybe that's not enough for you, so here's an example "upload.php" file that you can use to study and adjust your code. This code doesn't save any file, doesn't include any security check, it doesn't check for errors... It's just some basic sample explaining what you can do.

<?php

// This is just a simple example, not to be used in production!!!

// ------------------------
// Input parameters: optional means that you can ignore it, and required means that you
// must use it to provide the data back to CKEditor.
// ------------------------

// Optional: instance name (might be used to adjust the server folders for example)
$CKEditor = $_GET['CKEditor'] ;

// Required: Function number as indicated by CKEditor.
$funcNum = $_GET['CKEditorFuncNum'] ;

// Optional: To provide localized messages
$langCode = $_GET['langCode'] ;

// ------------------------
// Data processing
// ------------------------

// The returned url of the uploaded file
$url = '' ;

// Optional message to show to the user (file renamed, invalid file, not authenticated...)
$message = '';

// In FCKeditor the uploaded file was sent as 'NewFile' but in CKEditor is 'upload'
if (isset($_FILES['upload'])) {
    // ToDo: save the file :-)
    // Be careful about all the data that it's sent!!!
    // Check that the user is authenticated, that the file isn't too big,
    // that it matches the kind of allowed resources...
    $name = $_FILES['upload']['name'];

    // example: Build the url that should be used for this file   
    $url = "/images/" . $name ;
    // Usually you don't need any message when everything is OK.
//    $message = 'new file uploaded';   
}
else
{
    $message = 'No file has been sent';
}
// ------------------------
// Write output
// ------------------------
// We are in an iframe, so we must talk to the object in window.parent
echo "<script type='text/javascript'> window.parent.CKEDITOR.tools.callFunction($funcNum, '$url', '$message')</script>";

?>

If the code is deemed worth, it might be added to the wiki (for example in Custom File Browser, or creating a new article "Custom Uploader") but before doing so I would like to hear a little feedback.

 

Update 10/08/2013:

I've added the missing part to save the file, use it at your own risk. Go to the new post explaining it.

11 comments:

Rilwis said...

A very good article. I was searching every where but there's no implement of simple upload script like here. Even in the homepage of CKEditor, there's lack of information.

Thank you very much for this post.

sysdent said...

Muchas gracias por el artículo realmente me ha servido.

EySie said...

hi, is it okay to ask for a complete upload image php file? please & thanks!

Alfonso said...

No. It's not OK because there is never "a complete" sample.

I can add the call to save the file to disk, but they you would ask how to change the path. Or why it doesn't work if you have safe mode enabled. Or how it can be integrated with some CMS. Or a fix for Apache version X with PHP version Y running Z distro that two other people have heard of.

Just search for how to save a file with PHP and when you have that code working put it in the blanks of this sample. This is an example for integration with CKEditor, not a PHP tutorial.

Timbits said...

Absolutely great - that magic $_FILES['upload'], and the fact that we're in an iframe...

THANK YOU!

Tim

razvann said...

how to create a button that allows you to upload other file types, and CKEditor inserts a link in the text ?

Alfonso said...

You can copy the code from the link plugin and adjust it to your needs.

Primoz Frelih said...

Thanks Alfonso. This has been by far the simplest explanation.

svoka said...

Thanks a lot! It's really helpfull!

Unknown said...

Thank you!! Helped me a lot!

Great explanation!


I've used move_uploaded_file to do the upload.

greetings Andy

Yidir said...

GREAT POST !! :D Just use this and works fine :
window.parent.CKEDITOR.tools.callFunction($funcNum, '$url', '$message')<-/script>";

?>
(remove '-' script)
THANKS <3