Revision as of 15:34, 5 December 2011

CKReleaser is an application that exports CKEditor code, making all changes, replacements, and compilations necessary to build a public release of CKEditor. It is a command line program, with the following execution syntax:

ckreleaser [source_dir] [target_dir] [version] [zip_name] [gzip_name]

• source_dir – the path to the development code of CKEditor.
• target_dir – the path to the output directory.
• version – the version string used to replace the %VERSION% directive.
• zip_name – the .zip file containing the compressed version of the release.
• gzip_name – the .tar.gz file containing the compressed version of the release.

At the end of the process, the target_dir directory will be created and it will contain a directory named release, with the uncompressed version of the release files as well as the distribution files (in .zip and .gzip formats).

The execution fails if the target_dir already exists.

Configuration File

CKReleaser uses a configuration file that contains precise information about the tasks to be performed to build a release. The default configuration file for CKEditor is called ckeditor.release. The following are its contents:

fixLineEnds : true,

ignore :
[
	'_dev',
	'.svn',
	'.settings',
	'.project',
	'.idea'
],

copy :
[
	{
		source : '_source/lang',
		target : 'lang',
		minify : true
	},

	{
		source : '_source/adapters',
		target : 'adapters',
		minify : true
	},

	{
		source : '_source/plugins',
		target : 'plugins',
		minify : true,
		ignore :
		{
			sourcePackage : 'ckeditor.pack',
			files : 'packages[1].files'
		}
	},

	{
		source : '_source/themes',
		target : 'themes',
		minify : true
	}
],

rename :
[
],

packages :
[
	'ckeditor.pack'
],

skins :
{
	source : '_source/skins',
	target : 'skins',
	minify : true
}

Note that the configuration file uses the syntax of a JavaScript literal object declaration. This is intentional, and actually it is also possible to use JavaScript code inside the file. The entire file will then be loaded as a literal object declaration and interpreted as JavaScript code.

The following are the main entries available in the configuration:

• fixLineEnds – indicates that the fixlineends application is to be run in the *output* folder at the end of the process.
• ignore – a list of files and folder paths that are to be ignored by CKReleaser.
• copy – a list of objects identifying files and folders to be copied to different directories in the release package. The minify argument specifies whether .js and .css files are to be minified when outputting (see "Minification" below).
• packages – a list of configuration files to be executed by CKPackager.
• documentation – information needed to build the API documentation (see "Documentation" below).
• samples – information about the _samples folder, including its location and the path to the template file (see "Samples" below).
• skins – information about the skins location (see "Skins" below).

Minification

The process of reducing the size of JavaScript and CSS files by removing spaces, comments, etc. from it is called minification. Several files are to be minified on the output. We are using CKPackager to minify our source code.

Documentation

The CKEditor JavaScript API documentation is generated automatically by CKReleaser. It uses JsDoc Toolkit to build a pure HTML reference, extracting the documentation structure and text from the CKEditor source code.

CKReleaser runs JsDoc Toolkit over a configuration file present in the source directory and outputs it directly to the target directory.

Samples

The _samples folder contains a set of examples that show CKEditor in action. The development version of the samples uses a template system to provide a standard output to all samples.

The template file is called sample.html. All other .html files located in that folder (source files) contain data used to fill the template.

The source files are XML files containing several nodes with specific IDs that we use to locate the data to be loaded into the template. The following is a list of possible IDs:

• headscript (optional) – contains sample-specific script to be loaded into the <head> element.
• styles (optional) – contains sample-specific styles.
• html – contains the HTML data that effectively represents the sample.
• code – contains the sample code used to illustrate the API usage in the sample.

The template file contains <script> tags with the same IDs used in the source that need to be replaced by CKReleaser and filled with the source data. For example, the following is the original tag used to embed the html data:

<script id="html" type="text/javascript">
//<![CDATA[
	document.write( CKEDITOR.samples.htmlData );
//]]>
</script>

CKReleaser removes the above tag, replacing it with the contents of the source node with an ID of html. The headscript and styles data are special cases, because other than the data contents, the specific <script> and <style> tags must also be included.

The original source file names must be used for the release version, containing the template-filled version of each sample. The template file itself will not be part of the release.

Skins

CKEditor skin files consist of a set of CSS, JavaScript, and graphic files, grouped for each skin inside the skins folder.

Other than the JavaScript files minification, there is a particular processing procedure that needs to be performed on the skin files. All @import directives found in the files must be replaced with the effective contents of the imported files, and those imported files are not to be released.

For example, the release of the default skin should end up with only two CSS files: editor.css and dialog.css. The former is actually a combination of reset.css, mainui.css, toolbar.css and elementspath.css, which are not released directly.

Directives

CKReleaser makes a "file by file" copy from the source to the target. As part of this task, it searches for special character combinations (directives) in text files and processes them accordingly.

The following list contains the directives that can be processed:

• %VERSION% – the version string passed to the CKReleaser execution command.
• %TIMESTAMP% – a four-character string with the concatenation of the "Base 36" value of each of the following components of the program execution date and time: year + month + day + hour.
• %REMOVE_LINE% – removes the line.
• %REMOVE_START% and %REMOVE_END% – removes all lines starting from %REMOVE_START% and ending with %REMOVE_END%, declaration line inclusive.