Revision as of 14:17, 5 December 2011

CKReleaser

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 containing 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',
	'_docs/api',
	'_samples',
	'_source/adapters'
],

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

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

	{
		source : '_source/tests',
		target : 'tests',
		minify : false
	},

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

packages :
[
	'ckeditor.pack'
],

documentation :
{
	config: '_dev/docs_build/docs_build.conf',
	target: '_docs/api'
},

samples :
{
	source : '_samples',
	template : '_samples/samples.html'
},

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

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 into the file. The entire file will be then 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. 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'll be using CKPackager to minify our source code.

Documentation

The JavaScript API documentation is automatically generated 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, outputting 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 used to locate the data to be loaded into the template. The following are the possible ids:

• headscript (optional): contains sample specific script to be loaded in the <head>.
• 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 instead contains <script> tags with the same ids used in the source, that need to be replaced by CKReleaser, filling them 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 id "html". The "headscript" and "styles" data are special cases, because other than the data contents, the specific <script> and <style> tags must be also included.

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

Skins

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

Other than the JavaScript files minification, there is a particular processing 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 instead.

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.