Revision as of 11:17, 7 April 2011

CKPackager (or the package file generator) is a compact tool that is used to compress JavaScript files in order to optimize the application loading time. CKPackager minifies JavaScript source code of CKEditor. Due to the fact that it merges numerous files into one ckeditor.js file it also reduces the number of HTTP requests to the server.

CKPackager Purpose

If you modify CKEditor source code and would like to generate the ckeditor.js file anew, CKPackager is the right tool to use. Please note that you do not need to re-pack CKEditor and thus utilize the package file generator if you created your own plugin or modified a file that is not a part of ckeditor.js.

CKEditor Source

The JavaScript code of CKEditor is delivered as one main ckeditor.js where all the code has been compressed and merged (of course, not ALL the code, just the code that is needed for the core and the default plugins — the code of the dialog windows, for example, is loaded on demand). When you customize CKEditor and change its source code, it makes sense to use our package file generator to compress your own code.

CKPackager Basics

Start with downloading the ckpackager.jar file from http://svn.ckeditor.com/CKPackager/trunk/bin/ckpackager.jar and put it at the root of your CKEditor folder. There is also a ckpackager.exe file for those using the Windows operating system without Java installed; you can download it from here: http://svn.ckeditor.com/CKPackager/trunk/bin/ckpackager.exe. Please note that both files are located in the SVN repository, so they should always contain the latest versions.

Backup the existing ckeditor.js and ckeditor_basic.js files, so that you could check that the process is working correctly.

The first step is to verify that your Java installation works correctly just like your environment, so open the console/terminal/command prompt. Navigate to the CKEditor folder and type the command that starts the compilation. If you have not changed anything in the _source folder, this should generate the files identical to the original ckeditor.js and ckeditor_basic.js .

java -jar ckpackager.jar ckeditor.pack

The generated JavaScript files may not be identical to the original ones due to some changes in the version of CKPackager used to compress the released version of CKEditor as well as some improvements made to CKPackager since that moment, but the overall should be similar and you should be able to use the new files without differences.

Working with Source Files

You can now try to apply some changes to the files located in the _source directory and test them using the ckeditor_source.js file. When you are ready to deploy the modified files, you just have to compress them all again. As always, you should be careful with your changes, because compressing the source means that any slight error can be fatal.

The new packager is based on Rhino, the JavaScript implementation in Java from the people at Mozilla. As it is an external solution, it is not entirely clear how it deals with missing semicolons and other minor issues that can be fatal for some compression systems. Obviously it is better to write clean code instead of relying on the tools to fix them.

Selecting Just What You Want

The ckeditor.js file includes all CKEditor plugins (but not all the plugin code: the dialog windows are lazy loaded only when needed). If you do not want to provide some specific options to your users, you can remove some plugins — not only from the editor toolbar, but also from the packaged JavaScript file. As a result you can end up with a much smaller ckeditor.js file.

In order to change what is included in the compressed JavaScript file you need to edit ckeditor.pack and remove the entries for plugins that you do not need.

Do not alter the entries under _source/core/*, because the editor will probably fail. Custom packaging means that you are creating your own CKEditor file that you will need to support by yourself.

An example of a possible modification would be to delete the following line in order to remove the elements path that displays HTML elements of the document at the bottom of the editor interface.

'_source/plugins/elementspath/plugin.js',

Please note that you can also use the removePlugins configuration value to remove the plugin, but it would mean that the plugin code would still be loaded.

config.removePlugins = 'elementspath'

If you want to get rid of it altogether and save some bytes on loading, you can modify the packager settings and recompress the files. The ckeditor.js file will now be approximately 2 kB smaller. Please note that since some plugins might depend on others to work, you need to be careful not to remove the files too rigorously. If you remove a default plugin, it must be marked as such with the removePlugins configuration setting or the editor will try to load it and will fail in the process.

Optimizing the Downloads

If you check the ckeditor.pack file, you can see that by default the language file is not compressed. This is due to the fact that the editor interface is localized to many languages and the English language file is not used by everyone. Packaging the lang/en.js file for everybody would mean a waste of bytes, but if you know that your users only speak one language, you can specify that language in the ckeditor.pack file and get it bundled along the others. This will increase the size of ckeditor.js, but those bytes would normally be downloaded separately in another request, so the editor will be slightly faster as this additional step would be eliminated.

At the bottom of the ckeditor.pack file you can see that the kama.js skin file is also being bundled in the compressed file. If you are using another skin, you can adjust that entry to remove the Kama skin file and put your own one, avoiding the extra download of your selected skin.

Note that if you are using some custom plugins, you can include them in the list as well, so that on loading they would be ready along the rest of CKEditor files and any extra delay in the usage of plugins would be eliminated.