CKSource Docs - User contributions [en]

Template:CKEditor Docs FrontPage

2012-11-27T12:37:14Z

Fredck:

http://a.cksource.com/e/1/img/logo-ckeditor-h100.png

<span class="introText">Bring rich editor features to your products and websites, providing your users with powerful tools to make creating Web content easier than ever and accessible to anyone.</span>

<ul>
<li class="homeMainDoc">[http://docs.ckeditor.com/ CKEditor 4 Documentation Website]</li>
<li class="homeMainDoc">[[CKEditor 3.x/Developers Guide|CKEditor 3 Developer's Guide]]</li>
<li class="homeMainDoc">[[CKEditor_3.x/Users_Guide|CKEditor 3 User's Guide]]</li>
<li class="homeMainDoc">[[CKEditor_3.x/Howto|CKEditor 3 HOWTOs]]</li>
<li class="homeMainDoc">[[CKEditor_3.x/Tutorials|CKEditor 3 Tutorials]]</li>
<li class="homeMainDoc">[[CKEditor 3.x/Accessibility Compliance|CKEditor 3 Accessibility Compliance]]</li>
<li class="homeDoc">[[FCKeditor 2.x/Developers Guide|FCKeditor 2 Developer's Guide]]</li>
<li class="homeDoc">[[FCKeditor 2.x/Users Guide|FCKeditor 2 User's Guide]]</li>
<li class="homeSite">[http://ckeditor.com/ CKEditor Web Site]</li>
</ul>

Template:CKEditor Docs FrontPage

2012-11-27T12:36:42Z

Fredck:

http://a.cksource.com/e/1/img/logo-ckeditor-h100.png

<span class="introText">Bring rich editor features to your products and websites, providing your users with powerful tools to make creating Web content easier than ever and accessible to anyone.</span>

<ul>
<li class="homeMainDoc">[[http://docs.ckeditor.com/|CKEditor 4 Documentation Website]]</li>
<li class="homeMainDoc">[[CKEditor 3.x/Developers Guide|CKEditor 3 Developer's Guide]]</li>
<li class="homeMainDoc">[[CKEditor_3.x/Users_Guide|CKEditor 3 User's Guide]]</li>
<li class="homeMainDoc">[[CKEditor_3.x/Howto|CKEditor 3 HOWTOs]]</li>
<li class="homeMainDoc">[[CKEditor_3.x/Tutorials|CKEditor 3 Tutorials]]</li>
<li class="homeMainDoc">[[CKEditor 3.x/Accessibility Compliance|CKEditor 3 Accessibility Compliance]]</li>
<li class="homeDoc">[[FCKeditor 2.x/Developers Guide|FCKeditor 2 Developer's Guide]]</li>
<li class="homeDoc">[[FCKeditor 2.x/Users Guide|FCKeditor 2 User's Guide]]</li>
<li class="homeSite">[http://ckeditor.com/ CKEditor Web Site]</li>
</ul>

CKEditor 4.x/Skin SDK/Build

2012-07-26T16:35:18Z

Fredck: Created page with "{{#CUSTOMTITLE:Building and Releasing Your Skin}} So far, you've worked on the "source version" of your skin. Now that your skin is perfect as you wanted, it is time to prepar..."

{{#CUSTOMTITLE:Building and Releasing Your Skin}}
So far, you've worked on the "source version" of your skin. Now that your skin is perfect as you wanted, it is time to prepare it to be used in production websites.

To do so you'll need CKBuilder a Java application that makes this magic happen. It can be downloaded here:<br/>
http://download.cksource.com/ckbuilder/ckbuilder.jar <strong style="color:red">[TODO: Fix this URL]</strong>.

[http://java.com/en/download/ Java] must be available on your command line. To run the builder, simply copy <code>ckbuilder.jar</code> into the <code>skins</code> folder of CKEditor (where your skin custom folder is available) and execute this command:

> java -jar ckbuilder.jar --build-skin myskin myskin-release

The <code>myskin</code> and <code>myskin-release</code> parts are your skin folder name and the destination folder name. Just use the names you prefer.

This is the job done by CKBuilder on your skin:

* Merges all CSS files parts. This means that all CSS files having <code>@import</code> entries will have their imported files in-lined, having just one file available.
* Minifies CSS and JavaScript files, reducing their size to optimize the download speed.
* Generates a single "strip image" containing all icons provided by the skin.
* Removes all unnecessary files.

You skin is ready. The release version is the one to use on your websites or to distribute to others, while the source version can be shared to the world through services like [http://github.com/ GitHub].

CKEditor 4.x/Skin SDK/Test

2012-07-26T16:27:27Z

Fredck: Created page with "{{#CUSTOMTITLE:Testing and Shaping It Up}} Once you have your skin working in the way you want in one browser, it is time to test it on others. For that, just open a CKEditor ..."

{{#CUSTOMTITLE:Testing and Shaping It Up}}
Once you have your skin working in the way you want in one browser, it is time to test it on others. For that, just open a CKEditor sample with your skin on other browsers. Check out the CKSource GBS for the list of browsers supported by CKEditor.

Other things to test among all browsers are:

* Add <code>config.language='he';</code> to the CKEditor config.js file to load the editor in Hebrew and see the editor in RTL.
* Enable High Contrast on Windows (<code>SHIFT+ALT+PRINT-SCREEN</code>) and reload the page.
* Play with the the UI Color sample to check the chameleon feature.

CKEditor 4.x/Skin SDK/Customize

2012-07-26T16:25:20Z

Fredck:

{{#CUSTOMTITLE:Bringing Your Skin to Life}}
At this stage you have a started a skin that is eventually identical to the existing one you have chosen. Now it is time to bring your ideas to life, by making changes to the skin files.

The bad part of basing your work on an existing skin is the tendency of making both skins too similar. Or to reuse many of the solutions proposed on the base skin. Because of this, try to see your skin with different eyes and keep in mind that you can change it drastically if you want, having something that has nothing to do with the original skin.

To start, it is recommended opening all files in the skin folder and understanding their scope and contents. The Kama skin is fully documented, so its files are the best learning resources for in-depth technical aspects.

Skin developers have powerful tools available, which make it easy to work on CSS files. The most important tool is the "elements inspector", available in applications like [http://getfirebug.com/ Firebug] (for Firefox), [http://www.opera.com/dragonfly/ Opera Dragonfly] or the [https://developers.google.com/chrome-developer-tools/ Google Chrome Developer Tools]. With this tools you can change or add CSS style rules to elements and see the results on the fly. Then just port the changes to the CSS files. We strongly recommend this approach.

CKEditor 4.x/Skin SDK/Customize

2012-07-26T16:21:56Z

Fredck: Created page with "{{#CUSTOMTITLE:Bringing Your Skin to Life}} At this stage you have a started a skin that is eventually identical to the existing one you have chosen. Now it is time to bring y..."

{{#CUSTOMTITLE:Bringing Your Skin to Life}}
At this stage you have a started a skin that is eventually identical to the existing one you have chosen. Now it is time to bring your ideas to life, by making changes to the skin files.

The bad part of basing your work on an existing skin is the tendency of making both skins too similar. Or to reuse many of the solutions proposed on the base skin. Because of this, try to see your skin with different eyes and keep in mind that you can change it drastically if you want, having something that has nothing to do with the original skin.

To start, it is recommended opening all files in the skin folder and understanding their scope and contents. The Kama skin is fully documented, so its files are the best learning resources for in-depth technical aspects.

Skin developers have powerful tools available, which make it easy to work on CSS files. The most important tool is the "elements inspector", available in applications like Firebug (Firefox), Opera Dragonfly or the Developer Tools of Google Chrome. With this tools you can change or add CSS style rules to elements and see the results on the fly. Then just port the changes to the CSS files. We strongly recommend this approach.

CKEditor 4.x/Skin SDK/Setup

2012-07-26T16:20:16Z

Fredck: Created page with "{{#CUSTOMTITLE:Setting It Up to Start a Custom Skin}} The starting point of developing a skin is choosing an existing skin to base your work on. Starting a skin from scratch i..."

{{#CUSTOMTITLE:Setting It Up to Start a Custom Skin}}
The starting point of developing a skin is choosing an existing skin to base your work on. Starting a skin from scratch is possible, but it is a lot of work. Actually, it is up to the skin developer to decide the road to take, but generally existing skins are good enough. We recommend the default [[CKEditor_4.x/Skin_SDK/Introduction|Kama skin]] as the basis, because it is actively maintained and includes all possible features a skin can have.

You must have access to the "source files" of the selected skin. Distribution files are usually optimized for final use and are unreadable. Copy the source files in a folder inside the <code>skins</code> folder of a CKEditor installation. Give the folder name the name of your new skin (lower-cased, no spaces).

Now set the skin name in the CKEditor configuration file (<code>config.js</code>). For example: <code>config.skin=’myskin’;</code>

You're done, CKEditor will now start using your new skin files.

CKEditor 4.x/Skin SDK/Browser Hacks

2012-07-26T16:16:35Z

Fredck: Created page with "{{#CUSTOMTITLE:Dedicated Browser Hacks}} Skins are basically CSS styling on the DOM structure that represents the editor. Fortunately the world is going into a direction where..."

{{#CUSTOMTITLE:Dedicated Browser Hacks}}
Skins are basically CSS styling on the DOM structure that represents the editor. Fortunately the world is going into a direction where browsers are aligning their CSS features to standards, which makes it easier to design CSS that works everywhere.

But still the world is not perfect and we have small differences on CSS among browsers. Additionally, CKEditor must support ancient browsers, which are more limited and buggy.

To make it easier to maintain the skin CSS, CKEditor makes it possible to define browser specific files, which hold all "hacks" necessary for them. For example, a skin can contain the <code>editor_ie.css</code> file with all IE hacks or <code>dialog_opera.css</code> for Opera specific stuff.

A skin must instruct CKEditor to load, for example, <code>editor_ie.css</code> instead of <code>editor.css</code> on IE browsers. This must be done by setting the <code>CKEDITOR.skin.ua_editor</code> value to the list of "browser files" available. The same can be done for <code>dialog.css</code>. Check out the <code>skin.js</code> file of the [[CKEditor_4.x/Skin_SDK/Introduction|Kama skin]] for a real example.

CKEditor 4.x/Skin SDK/High Contrast

2012-07-26T16:13:46Z

Fredck: Created page with "{{#CUSTOMTITLE:High Contrast Compatibility}} The MS Windows operating systems offers an accessibility feature called "High Contrast", which turns the entire system UI into a t..."

{{#CUSTOMTITLE:High Contrast Compatibility}}
The MS Windows operating systems offers an accessibility feature called "High Contrast", which turns the entire system UI into a two colors environment. This can be controlled by the user, but usual we have "black on white" or "white on black". This feature is used by people with sight disabilities that makes it hard to identify contrast differences on object colors.

In High Contrast, all colors go away. Most of the applications UIs because just lines and boxes holding text labels or black and white icons.

To quickly enable High Contrast easily on Windows, just use <code>SHIFT+ALT+PRINT-SCREEN</code>. Do that now! Additional settings can be controlled in the Windows Control Panel.

CKEditor offers great support for High Contrast, limited to Firefox and Internet Explorer (other browsers don't support High Contrast). When enabled, the editor is rendered as clear lines and the toolbar buttons present text labels, instead of icon images.

Skin developers must take this in consideration and make the necessary CSS styling to support High Contrast. This can be easily done by using the <code>.cke_hc</code> class name, which is set at the outer element of the editor UI. Usage examples can be find in the [[CKEditor_4.x/Skin_SDK/Introduction|Kama skin]] files.

CKEditor 4.x/Skin SDK/RTL

2012-07-26T16:09:14Z

Fredck: Created page with "{{#CUSTOMTITLE:Right-to-Left (RTL) Reading Direction}} Most of us are used to read text from the left side of the page to the right, just like this text in English. This sound..."

{{#CUSTOMTITLE:Right-to-Left (RTL) Reading Direction}}
Most of us are used to read text from the left side of the page to the right, just like this text in English. This sounds obvious, but on several languages used around the world this is not true. They're read starting at the right to the left. This is known as the "RTL" reading (or writing) direction. Some of these languages are Arabic, Hebrew, Persian and Uyghur.

On software, RTL is an important aspect and it is well supported by Operating System and their applications. CKEditor is not an exception and offers exceptional support for RTL user interfaces.

Not that, for an application, RTL means that everything that we're used to see at one side of the screen, goes to the opposite side. If the close button is at top-right, it is move to top-left on RTL. A toolbar starts on the left, it'll then start on the right. It is like seeing the application in a mirror.

Skin developers must take this in consideration and make the necessary CSS styling to support RTL interfaces. This can be easily done by using the <code>.cke_rtl</code> class name, which is set at the outer element of the editor UI. Usage examples can be find in the [[CKEditor_4.x/Skin_SDK/Introduction|Kama skin]] files.

CKEditor 4.x/Skin SDK/Reset

2012-07-26T16:05:23Z

Fredck:

{{#CUSTOMTITLE:Reset and External CSS}}As we know, CKEditor is used inside webpages. In fact, the CKEditor UI and the skin CSS files are all loaded inside a page that is out of the editor and skin control. This means that the skin can have interference from external CSS present on the page.

Let's suppose a site likes red links. By simply adding <code>a{color:red;}</code> in a CSS file would be enough to make the toolbar labels or dialog tabs of the editor red.

To workaround this problem, a skin developer must include "reset styles" that will define defaults for most of the styles that could impact on the editor interface. Check the <code>reset.css</code> file in the [[CKEditor_4.x/Skin_SDK/Introduction|Kama skin]]. It is a useful base for it.

CKEditor 4.x/Skin SDK/Chameleon

2012-07-26T16:03:57Z

Fredck: Created page with "{{#CUSTOMTITLE:The "Chameleon" Feature}}One nice feature of CKEditor is its flexibility to easily match a website color scheme by simply setting the <code>config.uiColor</code..."

{{#CUSTOMTITLE:The "Chameleon" Feature}}One nice feature of CKEditor is its flexibility to easily match a website color scheme by simply setting the <code>config.uiColor</code> configuration option. While the Barbie site would set it to <code style="background:#F59FC6">#F59FC6</code>, Ninja Turtles would prefer <code style="background:#B1CC3D">#B1CC3D</code>.

The core editor API controls the input of the preferred color, but it is the skin job to tell it how to change the color. That's because the skin itself defined where and how to use colors.

For that purpose, the <code>CKEDITOR.skin.chameleon</code> function must be defined in the <code>skin.js</code> file. Please check the [[CKEditor_4.x/Skin_SDK/Introduction|Kama skin]] files for full details.

Note that adopting this feature is totally optional. A skin developer may decide to have a fixed color and not give the possibility to change it. Of course we don’t recommend this, but if that is the case, it is enough to not defined the chameleon function in the <code>skin.js</code> file.

CKEditor 4.x/Skin SDK/Reset

2012-07-26T15:57:36Z

Fredck: Created page with "As we know, CKEditor is used inside webpages. In fact, the CKEditor UI and the skin CSS files are all loaded inside a page that is out of the editor and skin control. This mea..."

As we know, CKEditor is used inside webpages. In fact, the CKEditor UI and the skin CSS files are all loaded inside a page that is out of the editor and skin control. This means that the skin can have interference from external CSS present on the page.

Let's suppose a site likes red links. By simply adding <code>a{ color:red; }</code> in a CSS file would be enough to make the toolbar labels or dialog tabs of the editor red.

To workaround this problem, a skin developer must include "reset styles" that will define defaults for most of the styles that could impact on the editor interface. Check the <code>reset.css</code> file in the [[CKEditor_4.x/Skin_SDK/Introduction|Kama skin]]. It is a useful base for it.

CKEditor 4.x/Skin SDK/Icons

2012-07-26T15:55:18Z

Fredck: Created page with "An important aspect that a skin can (optionally) customize are the icons used on the CKEditor toolbar and context menu. This is not mandatory in any way, but it makes it possi..."

An important aspect that a skin can (optionally) customize are the icons used on the CKEditor toolbar and context menu. This is not mandatory in any way, but it makes it possible to precisely align the icons design with the skin lines.

The CKEditor toolbar is filled by buttons provided by plugins. These plugins include default icons for their buttons. The skin role here is eventually overriding those icons, by providing a different version of them. This means that, if a skin icon is available for a button, it will be used, otherwise the default plugin icon is used.

There is a huge number of plugins available for CKEditor, provided by people and companies all around the world. It is impossible for a skin developer to provide icons for every single plugin, so it is up to her to decide which icons to include.

All skin icons must be included inside the <code>icons</code> folder in the skin folder. The icons file name must match the name of the icon files available in the <code>icons</code> folder of the plugins.

If you want the source version of your skin to overload icons properly, you must inform CKEditor about the presence of your custom icons. This is optional, but if not done your icons will be visible in the release version of your skin only. Check the <code>skin.js</code> file in the [[CKEditor_4.x/Skin_SDK/Introduction|Kama skin]] for an example.

CKEditor 4.x/Skin SDK

2012-07-26T15:50:39Z

Fredck:

{{#CUSTOMTITLE:CKEditor 4 Skin SDK}}The '''CKEditor 4 Skin SDK''' is the essential resource to successfully develop skins for CKEditor 4.

== Table of Contents ==

* [[CKEditor_4.x/Skin_SDK/Introduction|Introduction (Read me First!)]]
* Advanced Concepts on Skins
** [[CKEditor_4.x/Skin_SDK/Icons|Icons]]
** [[CKEditor_4.x/Skin_SDK/Reset|Reset and External CSS]]
** [[CKEditor_4.x/Skin_SDK/Chameleon|The "Chameleon" Feature]]
** [[CKEditor_4.x/Skin_SDK/RTL|Right-to-Left (RTL) Reading Direction]]
** [[CKEditor_4.x/Skin_SDK/High Contrast|High Contrast Compatibility]]
** [[CKEditor_4.x/Skin_SDK/Browser Hacks|Dedicated Browser Hacks]]
* Creating a Custom Skin
** [[CKEditor_4.x/Skin_SDK/Setup|Set It Up]]
** [[CKEditor_4.x/Skin_SDK/Customize|Bring Your Skin to Life]]
** [[CKEditor_4.x/Skin_SDK/Test|Test and Shape It Up]]
** [[CKEditor_4.x/Skin_SDK/Build|Build and Release Your Skin]]
* [[CKEditor_4.x/Skin_SDK/Resources|Resources and Downloads]]

CKEditor 4.x/Skin SDK/Introduction

2012-07-26T15:49:48Z

Fredck: Created page with "== What is a Skin? == A skin is an add-on for CKEditor that makes it possible to change the look and feel of its user interface (UI). Several aspects of the UI can be customi..."

== What is a Skin? ==

A skin is an add-on for CKEditor that makes it possible to change the look and feel of its user interface (UI). Several aspects of the UI can be customized by a skin, including colors, fonts, sizes, styles and icons.

== The "Kama" Skin ==

The '''Kama''' skin is currently the default skin of CKEditor. It is the one included on the standard CKEditor distributions. It is actively maintained by the CKEditor core developers and should be used as the starting point for the creation and maintenance of custom skins.

== The Anatomy of a Skin ==

A skin is, technically speaking, represented by a set of files, grouped inside a directory.

When CKEditor is used into a website, the following skin files are loaded in the page:

* '''skin.js''': registers the skin and makes it possible to optionally use some special skin features.
* '''editor.css''': contains the CSS styles used by the main editor interface.
* '''dialog.css''': loaded on demand, when a dialog is opened. Contains dialog specific CSS styles.

Actually, the above are the minimum set of files to be downloaded, but generally several other files are used, to make the skin easier to maintain and more logically organized.

In this document, we’ll not go on depth details about the files contents. For that, you should check the files available on the “Kama” skin. All files are well documented and are very self-descriptive.

CKEditor 4.x/Skin SDK

2012-07-26T15:45:48Z

Fredck:

{{#CUSTOMTITLE:CKEditor 4 Skin SDK}}The '''CKEditor 4 Skin SDK''' is the essential resource to successfully develop skins for CKEditor 4.

== Table of Contents ==

* [[CKEditor_4.x/Skin_SDK/Introduction|Introduction (Read me First!)]]
* [[CKEditor_4.x/Skin_SDK/Concepts|Advanced Concepts on Skins]]
** [[CKEditor_4.x/Skin_SDK/Icons|Icons]]
** [[CKEditor_4.x/Skin_SDK/Reset|Reset and External CSS]]
** [[CKEditor_4.x/Skin_SDK/Chameleon|The "Chameleon" Feature]]
** [[CKEditor_4.x/Skin_SDK/RTL|Right-to-Left (RTL) Reading Direction]]
** [[CKEditor_4.x/Skin_SDK/High Contrast|High Contrast Compatibility]]
** [[CKEditor_4.x/Skin_SDK/Browser Hacks|Dedicated Browser Hacks]]
* [[CKEditor_4.x/Skin_SDK/Create a Skin|Creating a Custom Skin]]
** [[CKEditor_4.x/Skin_SDK/Setup|Set It Up]]
** [[CKEditor_4.x/Skin_SDK/Customize|Bring Your Skin to Life]]
** [[CKEditor_4.x/Skin_SDK/Test|Test and Shape It Up]]
** [[CKEditor_4.x/Skin_SDK/Build|Build and Release Your Skin]]
* [[CKEditor_4.x/Skin_SDK/Resources|Resources and Downloads]]

CKEditor 4.x/Skin SDK

2012-07-26T15:08:54Z

Fredck: Started the page.

{{#CUSTOMTITLE:CKEditor 4 Skin SDK}}The CKEditor 4 Skin SDK is the essential resource to successfuly develop skins for CKEditor 4.

FCKeditor 3.x/Design and Architecture/Coding Style

2012-01-02T10:23:22Z

Fredck: /* File Headers */

= Coding Style Guidelines =

These guidelines where defined based on mixed common standards mainly related to Java programming. It aims to reflect the generally accepted standards for JavaScript coding with some minor adjustments.

It is quite common to take the Java style to write JavaScript code, assuming it is a "cut-down" version of Java. Although JavaScript has an indirect relation with Java, apart from the similar "C
== General Recommendations ==

Any violation to the guide is allowed if it enhances readability.

If the name "CKEditor" is used, if must always be written with "CKE" uppercased concatenated with "ditor" in lowercase. The following usages are wrong: "CKeditor", "ckEditor", "CK Editor", etc. Exceptions are made for directories and file names, which must always be lowercased, and the CKEDITOR namespace name.

If the name "FCKeditor" is used, it must always be written with "FCK" uppercased concatenated with "editor" in lowercase. The following are wrong: "FckEditor", "FCKEditor", "fckEditor", "FCK Editor", and so on. Exception is made for directory names, where all chars "should" be in lowercase.

The name "JavaScript" should be written with both the "J" and "S" in uppercase. The following are wrong: "Javascript", "javascript", etc.

== Naming Conventions ==

=== Generic Name Conventions ===

The ROOT namespace has a fixed name: CKEDITOR.
<pre>CKEDITOR
</pre>
Names representing namespaces must be all lowercase.
<pre>CKEDITOR.dom, CKEDITOR.env, CKEDITOR.ui
</pre>
Names representing public classes and public global objects must be in PascalCase.
<pre>CKEDITOR.dom.Document, CKEDITOR.Util
</pre>
Names representing constants must be all UPPERCASE.
<pre>CKEDITOR.STATUS_COMPLETE, CKEDITOR.EDITMODE_WYSIWYG, CKEDITOR.CTRL
</pre>
Names representing public methods must be verbs and written in camelCase.
<pre>appendStyleSheet(), getElement (), setTimeout()
</pre>
Names representing public properties must be nouns and written in camelCase.
<pre>name, document, targetWindow
</pre>
Names representing private methods must be verbs and written in camelCase prefixed with an underscore.
<pre>_doInternalStuff()
</pre>
Names representing private properties must be nouns and written in camelCase prefixed with an underscore.
<pre>_internalCounter, _prefix
</pre>
Abbreviations and acronyms should not be uppercase when used as name.
<pre>setHtml(), XmlDocument
NOT
setHTML(), XMLDocument
</pre>
All names should be written in English.

=== Specific Name Conventions ===

The prefixes "get" and "set" may be used on methods that get or set properties which require computation.
<pre>setArrayCount(), getFormattedValue()
</pre>
The prefix "checkIs" may be used on methods which return boolean states which require computation.
<pre>checkIsValid(), checkIsEmpty()
</pre>
Abbreviations in names should be avoided.
<pre>getDirectoryName(), applicationCommand
NOT
getDirName(), appCmd
</pre>
== Files ==

All files must be named in all lower case.

Classes and global objects should be declared in individual files with the file name matching the class/object name.
<pre>fckbrowserinfo.js, fcktoolbarbutton.js
</pre>
== Layout ==

For indentation, the TAB should be used. Development IDEs should be configured to represent TABs as 4 spaces.
<pre>if ( test )
{
if ( otherTest )
doSomething();
doMore();
}
</pre>
Block layout should be as illustrated.
<pre>while ( !done )
{
doSomething();
done = moreToDo();
}
</pre>
Single statement (single line only) if/else/while/for could (preferably) be written without brackets, but never in the same line.
<pre>if ( condition )
statement;

while ( condition )
statement;

for ( initialization ; condition ; update )
statement;
</pre>
The above rule is not valid for nested blocks, like the following:
<pre>if ( condition )
{
if ( anotherCondition )
statement;
}

// WRONG:
if ( condition )
if ( anotherCondition )
statement;
</pre>
The incompleteness of split lines must be made obvious.
<pre>totalSum = a + b + c +
d + e;

method( param1, param2,
param3 );

setText( 'Long line split' +
'into two parts.' );
</pre>
=== Whitespace ===
"If", "for", "while" and "switch" should be followed by a white space.
<pre>if ( true )
NOT
if( true )
</pre>
Conventional operators should be surrounded by a space (including ternary operators).
<pre>if ( i > 3 && test == 'yes' )
</pre>
Commas should be followed by a space.
<pre>function myFunction( parm1, param2, param3 )
</pre>
Semi-colons in for statements should be surrounded by a space.
<pre>for ( var i = 0 ; i < count ; i++ )
</pre>
Semi-colons should not be preceded by a space.
<pre>doSomething();
var name = 'John';
</pre>
Colons should be surrounded by a space.
<pre>case 100 :
NOT
case 100:
</pre>
Opening parenthesis must be followed by a space and closing parenthesis must be preceded by a space.
<pre>if ( myVar == 1 )
</pre>
There special cases where no space is recommended. When opening parenthesis for a "self-executing anonymous function" and when closing parenthesis after an indented code block:
<pre>(function()
{
// Code here
})();

myMethod( function()
{
// Code here
});
</pre>
Functions/method calls should not be followed by a space.
<pre>doSomething( someParameter );
NOT
doSomething ( someParameter );
</pre>
Logical units within a block should be separated by one blank line.
<pre>// Create a new identity matrix
var matrix = new Matrix4x4();

// Precompute angles for efficiency
var cosAngle = mathCos( angle );
var sinAngle = mathSin( angle );

// Specify matrix as a rotation transformation
matrix.setElement( 1, 1, cosAngle );
matrix.setElement( 1, 2, sinAngle );
matrix.setElement( 2, 1, -sinAngle );
matrix.setElement( 2, 2, cosAngle );

// Apply rotation
transformation.multiply( matrix );
</pre>

Multiple variables declaration in a single "var" statement must be aligned with a single tab.

<pre>
var example = 1,
sample = 2;
NOT
var example = 1,
sample = 2;
</pre>

== Variables ==

Variables must be always defined with "var".

Function parameters must be in camelCase.
<pre>function sum( firstNumber, secondNumber )
</pre>
Local variables must be in camelCase.
<pre>function doSomething()
{
var colorOne = 1;
var colorTwo = 2;

return colorOne + colorTwo;
}
</pre>
Several variables can be defined with a single var statement, but only if their initialization values are in single lines. Do not initialize more than one variable is a single line:
<pre>var aVar, someVar,
other1Var = 10,
other2Var = 25,
isVar = true;

var longVar = function()
{
// This var takes more than one line.
};

var objVar =
{
// This var takes more than one line.
};
</pre>

== Comments ==

Tricky code should not be commented but rewritten: In general, the use of comments should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure.

All comments should be written in English. Whenever possible, end comments with a period as normal phrases, and wrap comments within the first 80 characters of each line.

There should be a space after the comment identifier.
<pre>// This is a comment. NOT: //This is a comment
/** NOT: /**
* This is block *This is a block
* comment. *comment
*/ */
</pre>
Note that comment blocks should be opened with two asterisks only for documentation purposes. See [[FCKeditor 3.x/Design and Architecture/Documentation#JavaScript_API|JavaScript API Documentation]].

== Regular Expressions ==

The '''regular expression literal''' should be used whenever possible, instead of the RegExp object, which should be used only when the regular expression pattern is not constant or depends on runtime computation.
<pre>/^foo\s*/i
NOT
new RegExp( '^foo\s*', 'i' )
</pre>
Other than shortnesses and better readability, regular expression literals are compiled during script evaluation, which improves performance at runtime.

== String Literals ==

When defining string literals, use single quotes instead of double quotes, whenever possible.

<pre>var s = 'Some text';
NOT
var s = "Some text";
</pre>

== File Headers ==

There are minimum requirements for us to be able to make our code available to the world. Most of them are related to legal needs, which help us protecting the project from abuses.

Here is a JavaScript template for the header to be included in the source code:
<pre>/*
Copyright (c) 2003-2012, CKSource - Frederico Knabben. All rights reserved.
For licensing, see LICENSE.html or http://ckeditor.com/license
*/
</pre>
Of course, different languages have different commenting syntax, so it is enough to copy the header from an existing file to maintain the style.

=== Author Tags ===

Author names, e-mails or web site addresses should be avoided in the header. To justify that, let me recall a citation from Sander Striker, a member of the Apache Software Foundation, that can be found at [http://producingoss.com/en/managing-volunteers.html#territoriality Producing Open Source Software]:
<blockquote>At the Apache Software foundation we discourage the use of author tags in source code. There are various reasons for this, apart from the legal ramifications. Collaborative development is about working on projects as a group and caring for the project as a group. Giving credit is good, and should be done, but in a way that does not allow for false attribution, even by implication. There is no clear line for when to add or remove an author tag. Do you add your name when you change a comment? When you put in a one-line fix? Do you remove other author tags when you refactor the code and it looks 95% different? What do you do about people who go about touching every file, changing just enough to make the virtual author tag quota, so that their name will be everywhere?<br> </blockquote> <blockquote>
There are better ways to give credit, and our preference is to use those. From a technical standpoint author tags are unnecessary; if you wish to find out who wrote a particular piece of code, the version control system can be consulted to figure that out. Author tags also tend to get out of date. Do you really wish to be contacted in private about a piece of code you wrote five years ago and were glad to have forgotten?<br>
</blockquote>
The SVN is a good place to understand user participation. Even when committing changes proposed by Joe White, it is nice to add a comment like "Thanks to Joe White." in the commit message.

FCKeditor 3.x/Design and Architecture/Coding Style

2012-01-02T10:22:23Z

Fredck: /* Comments */

= Coding Style Guidelines =

These guidelines where defined based on mixed common standards mainly related to Java programming. It aims to reflect the generally accepted standards for JavaScript coding with some minor adjustments.

It is quite common to take the Java style to write JavaScript code, assuming it is a "cut-down" version of Java. Although JavaScript has an indirect relation with Java, apart from the similar "C
== General Recommendations ==

Any violation to the guide is allowed if it enhances readability.

If the name "CKEditor" is used, if must always be written with "CKE" uppercased concatenated with "ditor" in lowercase. The following usages are wrong: "CKeditor", "ckEditor", "CK Editor", etc. Exceptions are made for directories and file names, which must always be lowercased, and the CKEDITOR namespace name.

If the name "FCKeditor" is used, it must always be written with "FCK" uppercased concatenated with "editor" in lowercase. The following are wrong: "FckEditor", "FCKEditor", "fckEditor", "FCK Editor", and so on. Exception is made for directory names, where all chars "should" be in lowercase.

The name "JavaScript" should be written with both the "J" and "S" in uppercase. The following are wrong: "Javascript", "javascript", etc.

== Naming Conventions ==

=== Generic Name Conventions ===

The ROOT namespace has a fixed name: CKEDITOR.
<pre>CKEDITOR
</pre>
Names representing namespaces must be all lowercase.
<pre>CKEDITOR.dom, CKEDITOR.env, CKEDITOR.ui
</pre>
Names representing public classes and public global objects must be in PascalCase.
<pre>CKEDITOR.dom.Document, CKEDITOR.Util
</pre>
Names representing constants must be all UPPERCASE.
<pre>CKEDITOR.STATUS_COMPLETE, CKEDITOR.EDITMODE_WYSIWYG, CKEDITOR.CTRL
</pre>
Names representing public methods must be verbs and written in camelCase.
<pre>appendStyleSheet(), getElement (), setTimeout()
</pre>
Names representing public properties must be nouns and written in camelCase.
<pre>name, document, targetWindow
</pre>
Names representing private methods must be verbs and written in camelCase prefixed with an underscore.
<pre>_doInternalStuff()
</pre>
Names representing private properties must be nouns and written in camelCase prefixed with an underscore.
<pre>_internalCounter, _prefix
</pre>
Abbreviations and acronyms should not be uppercase when used as name.
<pre>setHtml(), XmlDocument
NOT
setHTML(), XMLDocument
</pre>
All names should be written in English.

=== Specific Name Conventions ===

The prefixes "get" and "set" may be used on methods that get or set properties which require computation.
<pre>setArrayCount(), getFormattedValue()
</pre>
The prefix "checkIs" may be used on methods which return boolean states which require computation.
<pre>checkIsValid(), checkIsEmpty()
</pre>
Abbreviations in names should be avoided.
<pre>getDirectoryName(), applicationCommand
NOT
getDirName(), appCmd
</pre>
== Files ==

All files must be named in all lower case.

Classes and global objects should be declared in individual files with the file name matching the class/object name.
<pre>fckbrowserinfo.js, fcktoolbarbutton.js
</pre>
== Layout ==

For indentation, the TAB should be used. Development IDEs should be configured to represent TABs as 4 spaces.
<pre>if ( test )
{
if ( otherTest )
doSomething();
doMore();
}
</pre>
Block layout should be as illustrated.
<pre>while ( !done )
{
doSomething();
done = moreToDo();
}
</pre>
Single statement (single line only) if/else/while/for could (preferably) be written without brackets, but never in the same line.
<pre>if ( condition )
statement;

while ( condition )
statement;

for ( initialization ; condition ; update )
statement;
</pre>
The above rule is not valid for nested blocks, like the following:
<pre>if ( condition )
{
if ( anotherCondition )
statement;
}

// WRONG:
if ( condition )
if ( anotherCondition )
statement;
</pre>
The incompleteness of split lines must be made obvious.
<pre>totalSum = a + b + c +
d + e;

method( param1, param2,
param3 );

setText( 'Long line split' +
'into two parts.' );
</pre>
=== Whitespace ===
"If", "for", "while" and "switch" should be followed by a white space.
<pre>if ( true )
NOT
if( true )
</pre>
Conventional operators should be surrounded by a space (including ternary operators).
<pre>if ( i > 3 && test == 'yes' )
</pre>
Commas should be followed by a space.
<pre>function myFunction( parm1, param2, param3 )
</pre>
Semi-colons in for statements should be surrounded by a space.
<pre>for ( var i = 0 ; i < count ; i++ )
</pre>
Semi-colons should not be preceded by a space.
<pre>doSomething();
var name = 'John';
</pre>
Colons should be surrounded by a space.
<pre>case 100 :
NOT
case 100:
</pre>
Opening parenthesis must be followed by a space and closing parenthesis must be preceded by a space.
<pre>if ( myVar == 1 )
</pre>
There special cases where no space is recommended. When opening parenthesis for a "self-executing anonymous function" and when closing parenthesis after an indented code block:
<pre>(function()
{
// Code here
})();

myMethod( function()
{
// Code here
});
</pre>
Functions/method calls should not be followed by a space.
<pre>doSomething( someParameter );
NOT
doSomething ( someParameter );
</pre>
Logical units within a block should be separated by one blank line.
<pre>// Create a new identity matrix
var matrix = new Matrix4x4();

// Precompute angles for efficiency
var cosAngle = mathCos( angle );
var sinAngle = mathSin( angle );

// Specify matrix as a rotation transformation
matrix.setElement( 1, 1, cosAngle );
matrix.setElement( 1, 2, sinAngle );
matrix.setElement( 2, 1, -sinAngle );
matrix.setElement( 2, 2, cosAngle );

// Apply rotation
transformation.multiply( matrix );
</pre>

Multiple variables declaration in a single "var" statement must be aligned with a single tab.

<pre>
var example = 1,
sample = 2;
NOT
var example = 1,
sample = 2;
</pre>

== Variables ==

Variables must be always defined with "var".

Function parameters must be in camelCase.
<pre>function sum( firstNumber, secondNumber )
</pre>
Local variables must be in camelCase.
<pre>function doSomething()
{
var colorOne = 1;
var colorTwo = 2;

return colorOne + colorTwo;
}
</pre>
Several variables can be defined with a single var statement, but only if their initialization values are in single lines. Do not initialize more than one variable is a single line:
<pre>var aVar, someVar,
other1Var = 10,
other2Var = 25,
isVar = true;

var longVar = function()
{
// This var takes more than one line.
};

var objVar =
{
// This var takes more than one line.
};
</pre>

== Comments ==

Tricky code should not be commented but rewritten: In general, the use of comments should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure.

All comments should be written in English. Whenever possible, end comments with a period as normal phrases, and wrap comments within the first 80 characters of each line.

There should be a space after the comment identifier.
<pre>// This is a comment. NOT: //This is a comment
/** NOT: /**
* This is block *This is a block
* comment. *comment
*/ */
</pre>
Note that comment blocks should be opened with two asterisks only for documentation purposes. See [[FCKeditor 3.x/Design and Architecture/Documentation#JavaScript_API|JavaScript API Documentation]].

== Regular Expressions ==

The '''regular expression literal''' should be used whenever possible, instead of the RegExp object, which should be used only when the regular expression pattern is not constant or depends on runtime computation.
<pre>/^foo\s*/i
NOT
new RegExp( '^foo\s*', 'i' )
</pre>
Other than shortnesses and better readability, regular expression literals are compiled during script evaluation, which improves performance at runtime.

== String Literals ==

When defining string literals, use single quotes instead of double quotes, whenever possible.

<pre>var s = 'Some text';
NOT
var s = "Some text";
</pre>

== File Headers ==

There are minimum requirements for us to be able to make our code available to the world. Most of them are related to legal needs, which help us protecting the project from abuses.

Here is a JavaScript template for the header to be included in the source code:
<pre>/*
Copyright (c) 2003-2009, CKSource - Frederico Knabben. All rights reserved.
For licensing, see LICENSE.html or http://ckeditor.com/license
*/
</pre>
Of course, different languages have different commenting syntax, so it is enough to copy the header from an existing file to maintain the style.

=== Author Tags ===

Author names, e-mails or web site addresses should be avoided in the header. To justify that, let me recall a citation from Sander Striker, a member of the Apache Software Foundation, that can be found at [http://producingoss.com/en/managing-volunteers.html#territoriality Producing Open Source Software]:
<blockquote>At the Apache Software foundation we discourage the use of author tags in source code. There are various reasons for this, apart from the legal ramifications. Collaborative development is about working on projects as a group and caring for the project as a group. Giving credit is good, and should be done, but in a way that does not allow for false attribution, even by implication. There is no clear line for when to add or remove an author tag. Do you add your name when you change a comment? When you put in a one-line fix? Do you remove other author tags when you refactor the code and it looks 95% different? What do you do about people who go about touching every file, changing just enough to make the virtual author tag quota, so that their name will be everywhere?<br> </blockquote> <blockquote>
There are better ways to give credit, and our preference is to use those. From a technical standpoint author tags are unnecessary; if you wish to find out who wrote a particular piece of code, the version control system can be consulted to figure that out. Author tags also tend to get out of date. Do you really wish to be contacted in private about a piece of code you wrote five years ago and were glad to have forgotten?<br>
</blockquote>
The SVN is a good place to understand user participation. Even when committing changes proposed by Joe White, it is nice to add a comment like "Thanks to Joe White." in the commit message.

CKEditor 3.x/Tutorials/SimpleLink Plugin Part 1

2011-09-13T09:03:39Z

Fredck: Minor code fixes.

{{#CUSTOMTITLE:Creating a CKEditor Plugin with a Custom Dialog Window}}
__TOC__
The aim of this tutorial is to demonstrate how to create a custom plugin dialog window that contains various types of fields.

We are going to develop a '''Simple Link plugin''' that can replace the more feature-rich default [[CKEditor_3.x/Users_Guide/Rich_Text/Links|Link]] feature of CKEditor with a simplified solution. The plugin dialog window will let the user insert a link through a customized dialog window that is opened after clicking a dedicated toolbar button.

The plugin will be named <code>'''simpleLink'''</code>.

== Plugin Files ==
Firstly, we will need to create the <code>simpleLink</code> folder inside the <code>plugins</code> directory of the CKEditor installation.

<note>Remember that for CKEditor the name of the plugin folder is important and has to be the same as the name of the plugin, otherwise the editor will not be able to recognize it.</note>

Inside the newly created <code>simpleLink</code> folder we are going to place the <code>plugin.js</code> file that will contain the plugin logic. Apart from that, since we will also need a toolbar icon for our plugin, we are going to add an <code>images</code> folder and subsequently place the <code>icon.png</code> file inside.

To sum up, we will need the following file structure for our plugin to work:
* <code>''ckeditor root''</code>
** <code>plugins</code>
*** <code>simpleLink</code>
**** <code>images</code>
***** <code>icon.png</code>
**** <code>plugin.js</code>

== Plugin Source Code ==
With the following structure ready, it is time to open the <code>plugin.js</code> file in a text editor and to start creating the source code of the plugin.
<source lang="javascript">
CKEDITOR.plugins.add( 'simpleLink',
{
init: function( editor )
{
// Plugin logic goes here...
}
});
</source>
All CKEditor plugins are created by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.resourceManager.html#add CKEDITOR.plugins.add]</code> function. This function should contain the plugin name (<code>'simpleLink'</code>) and the plugin logic placed inside the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.pluginDefinition.html#init init]</code> function that is called upon the initialization of the editor instance.

=== Creating an Editor Command ===
We want our plugin to have a dialog window, so we need to define an editor command that opens a new dialog window. To do this, we will need to use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#addCommand addCommand]</code> function opening the <code>simpleLinkDialog</code> window that we are going to define in a moment by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialogCommand.html CKEDITOR.dialogCommand]</code> function.
<source lang="javascript">
editor.addCommand( 'simpleLinkDialog', new CKEDITOR.dialogCommand( 'simpleLinkDialog' ) );
</source>

=== Creating a Toolbar Button ===
The plugin dialog window is to be opened by using a toolbar button. To this end, we need to define a button that will be associated with the dialog window. The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.html#addButton CKEditor.ui.addButton]</code> function accepts a button name (<code>'SimpleLink'</code>) along with the definition of the tooltip text (<code>label</code>) and the button icon (<code>icon</code>). Note that <code>this.path</code> is the directory where the <code>plugin.js</code> file resides.

These parameters are responsible for the button presentation. To make the button actually work, we need to connect it to the plugin command name defined above by using the <code>command</code> parameter.
<source lang="javascript">
editor.ui.addButton( 'SimpleLink',
{
label: 'Insert a Link',
command: 'simpleLinkDialog',
icon: this.path + 'images/icon.png'
});
</source>

=== CKEditor Initialization ===
It is now time to initialize a CKEditor instance that will use the Simple Link plugin along with its toolbar button.

To register the plugin with CKEditor, we have to add it to the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.extraPlugins extraPlugins]</code> list. We also need to enhance the toolbar definition and add the plugin button by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.toolbar toolbar]</code> parameter.

Open the page that will contain CKEditor in a text editor, and insert a CKEditor instance using the following toolbar and plugin configuration.
<source lang="javascript">
<script type="text/javascript">

// Replace the <textarea id="editor1"> with a CKEditor instance using default configuration.
CKEDITOR.replace( 'editor1',
{
extraPlugins : 'simpleLink',
toolbar :
[
['Source', '-', 'Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', 'Unlink'],
['About','-','SimpleLink']
]
});

</script>
</source>

After you load the page containing the above CKEditor instance you should be able to see the new plugin toolbar button along with its tooltip.

[[Image:simpleLink_button_added.png|center|frame|SimpleLink plugin button added to CKEditor toolbar]]

=== Plugin Dialog Window ===
Up till now, most of the actions that we performed were equivalent to what we did while creating the [[CKEditor_3.x/Developers_Guide/Customization/Plugins/Abbr_Plugin_Part_1|Abbreviation]] plugin. Here is, however, where the really interesting part begins. We will now move on to creating a custom dialog window along with its contents.

Clicking the button should open the <code>simpleLinkDialog</code> dialog window. First, however, we need to return to the Simple Link plugin source file and [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html define the dialog window] by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html#.add CKEDITOR.dialog.add]</code> function. To see all dialog window definition elements, refer to [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html CKEditor JavaScript API].

In our case we will give the dialog window a name (<code>'simpleLinkDialog'</code>) and use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#title title]</code>, <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#minWidth minWidth]</code>, and <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#minHeight minHeight]</code> parameters to define its title and minimum dimensions, respectively.

<note>The name selected for the dialog window is the name that appears in the <code>addCommand</code> function above.
</note>

==== Dialog Window Tab ====
The dialog window should also contain some contents, so we will begin with adding a tab along with its label. In all CKEditor dialog windows the contents of a dialog window are defined iside the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#contents contents]</code> array. This array contains <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.contentDefinition.html CKEDITOR.dialog.contentDefinition]</code> objects that consititute the tabs (or "content pages") of a dialog window.

We will give our dialog window tab an <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.contentDefinition.html#id id]</code> and <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.contentDefinition.html#label label]</code>. Please note that since in our case the dialog window contains just one tab (or "page"), the tab's name (label) will not be visible. However, even though the <code>label</code> property is not required, it is a good practice to include it since it plays its role in accessibility support as it will be read aloud by screen readers.

Note that by default CKEditor also adds the standard '''OK''' and '''Cancel''' buttons. If you want to customize them (i.e. remove both or just one, add custom ones), you can use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.definition.html#buttons buttons]</code> array to add new <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.button.html button]</code> elements.

A dialog window tab created in this way should also contain some real content, like text fields, checkboxes, or drop-down lists. These will be added in the next step inside the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.contentDefinition.html#elements elements]</code> property.

In order to create the Simple Link plugin dialog window, add the following code in the <code>plugin.js</code> file below the plugin toolbar button definition.
<source lang="javascript">
CKEDITOR.dialog.add( 'simpleLinkDialog', function( editor )
{
return {
title : 'Link Properties',
minWidth : 400,
minHeight : 200,
contents :
[
{
id : 'general',
label : 'Settings',
elements :
[
// UI elements of the Settings tab.
]
}
]
};
});
</source>
The result of this change can be seen immediately. Click the '''Insert a Link''' toolbar button in order to open the newly created (and so far empty) '''Link Properties''' dialog window.

[[Image:simpleLink_empty_tab.png|center|frame|A SimpleLink plugin dialog window with one tab added]]

==== Dialog Window Tab Elements ====
User interface elements that can be added to a dialog window tab are defined in the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.contentDefinition.html#elements elements]</code> parameter, which is an array of <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.uiElementDefinition.html CKEDITOR.dialog.uiElementDefinition]</code> objects.

Since we want to try a number of different types of dialog window UI elements, in this case the dialog window tab will consist of a larger textarea, smaller text field, a selection field (drop-down list), and a checkbox. We will also use HTML to create the tab description.

Each UI element is added inside the <code>elements</code> array, with the definition placed inside the curly braces (<code>{}</code>), separated from one another with a comma. The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.uiElementDefinition.html#type type]</code> parameter is a required one and defines the type of the element.

===== UI Elements: HTML =====
The first UI element we are going to use is the HTML type. The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.html.html html]</code> type allows you to define the contents of a dialog window page by using pure HTML code. The HTML code to be placed inside the page is entered in the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.html.html#constructor html]</code> parameter.

<source lang="javascript">
elements :
[
{
type : 'html',
html : 'This dialog window lets you create simple links for your website.'
}
]
</source>

After adding the above code to the plugin source, the '''Link Properties''' dialog window looks like this.

[[Image:simpleLink_tab_html.png|center|frame|HTML element added in the SimpleLink plugin dialog window]]

===== UI Elements: Textarea =====
The element to be placed underneath the description is the textarea element that will be obligatory to fill in. We will use it to add the text that is displayed in the document and points to the inserted link.

In order to create a textarea we will use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.textarea.html textarea]</code> UI element type and assign it an <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.uiElementDefinition.html#id id]</code>. The textarea will also need a label that will describe its purpose and can be added using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.labeledElement.html#constructor label]</code> parameter.

Since filling in the contents of the textarea will be obligatory, we will set the <code>required</code> parameter to <code>true</code> and inside the <code>validate</code> parameter add some simple validation that checks whether the field is empty. If it is, the validator will return an error message.

<source lang="javascript">
{
type : 'textarea',
id : 'contents',
label : 'Displayed Text',
validate : CKEDITOR.dialog.validate.notEmpty( 'The Displayed Text field cannot be empty.' ),
required : true
}
</source>

This is the appearance of the '''Link Properties''' dialog window after we apply the changes.

[[Image:simpleLink_tab_textarea.png|center|frame|Textarea element added in the SimpleLink plugin dialog window]]

The size of the textarea can obviously be customized. If you want to change the element's dimensions, use the <code>cols</code> amd <code>rows</code> parameters as defined in the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.textarea.html#constructor textarea]</code> constructor.

===== UI Elements: Text Field =====
Another UI element that we are going to use in the plugin is the text field (text input) element. We will use it to enter the Internet address of the linked page.

A text field lets you enter text into a single-line field and is meant for shorter entries. Its definition is very similar to the textarea — the main difference lies in the <code>type</code> parameter that is set to <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.textInput.html text]</code>.

The <code>id</code> and <code>label</code> parameters will be defined as done above. In our case this field is obligatory, so we will set its <code>required</code> parameter to <code>true</code>. The validation code inside the <code>validate</code> parameter will also be used to check whether the field was filled in. If it is empty, the validator will return an error message.

<source lang="javascript">
{
type : 'text',
id : 'url',
label : 'URL',
validate : CKEDITOR.dialog.validate.notEmpty( 'The link must have a URL.' ),
required : true
}
</source>

With the latest addition of the text field the '''Link Properties''' dialog window will look like this.

[[Image:simpleLink_tab_text.png|center|frame|Text field element added in the SimpleLink plugin dialog window]]

===== UI Elements: Selection Field =====
Another type of UI elements that we are going to try out is the selection field (drop-down list). In this case we will use it to allow the user to choose one of the pre-defined styles for the link text.

To create a selection field we need to set the <code>type</code> parameter of the element to <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.select.html select]</code>. As before, we will add the <code>id</code> and <code>label</code> parameters appropriate for this field. The items to be chosen from the selection list are defined inside the obligatory <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.select.html#constructor items]</code> array that contains the values along with their displayed text. The first item defined in the list will be used by default; you can also use the <code>default</code> parameter to change this setting.

<source lang="javascript">
{
type : 'select',
id : 'style',
label : 'Style',
items :
[
[ '<none>', '' ],
[ 'Bold', 'b' ],
[ 'Underline', 'u' ],
[ 'Italics', 'i' ]
]
}
</source>

After the selection field is added to the plugin dialog window and is expanded by the user, the style that was selected by default (the first one, if not defined otherwise) is highlighted.

[[Image:simpleLink_tab_select.png|center|frame|Selection field element added in the SimpleLink plugin dialog window]]

===== UI Elements: Checkbox =====
The final UI element to be added to the plugin dialog window is the checkbox. In this case the user will be able to select it if the link is to be opened in a new window.

In order to create a checkbox we need to set the <code>type</code> parameter of the element to <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.dialog.checkbox.html checkbox]</code>. As before, the field will also get a standard <code>id</code> and <code>label</code>. Since we want opening in a new page to be a default behavior, we will set the <code>default</code> parameter to <code>true</code> in order to have the checkbox selected when the plugin dialog window is opened.

<note>Please note that the <code>default</code> parameter needs to be placed in single quotes since it is a reserved JavaScript word.
</note>

<source lang="javascript">
{
type : 'checkbox',
id : 'newPage',
label : 'Opens in a new page',
'default' : true
}
</source>

The figure below shows the '''Link Properties''' dialog window complete with all the UI elements added above.

[[Image:simpleLink_tab_checkbox.png|center|frame|Checkbox element added in the SimpleLink plugin dialog window]]

=== Plugin Behavior ===
The plugin now ''looks'' good — the toolbar button is in place and the dialog window is complete with a couple of sample UI elements. There is, however, one problem: it does not really ''do'' anything.

We will start with creating the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#onOk onOk]</code> method that is invoked once the user accepts the changes introduced in the dialog window by clicking the '''OK''' button or pressing the ''Enter'' key on the keyboard. The method will be defined inside the <code>CKEDITOR.dialog.add</code> function, below the definition of dialog window contents.

<source lang="javascript">
onOk : function()
{
// The code that will be executed when the user accepts the changes.
}
</source>

We shall start the <code>onOk</code> function from creating a link element and a <code>data</code> object that will store the data entered in the dialog window fields. The link will be based on a standard HTML <code><a></code> element and as a new DOM element it will be created by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.document.html#createElement createElement]</code> function.

<source lang="javascript">
var dialog = this,
data = {},
link = editor.document.createElement( 'a' );
</source>

In order to populate the <code>data</code> object with the contents of the dialog window fields we will use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html#commitContent commitContent]</code> function.

<source lang="javascript">
this.commitContent( data );
</source>

To make the <code>commitContent</code> function work we will however first need to define the commit functions themselves. In order to do that, we will have to revise the code of the dialog window UI elements again.

The commit functions will have to be added to all user input elements of the plugin dialog window — the textarea, the text field, the selection field, and the checkbox. In each case the functions need to get the value entered by the user by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#getValue getValue]</code> function and assign it to an appropriate attribute of the <code>data</code> object.

<source lang="javascript">
elements :
[
{
type : 'html',
html : 'This dialog window lets you create simple links for your website.'
},
{
type : 'textarea',
id : 'contents',
label : 'Displayed Text',
validate : CKEDITOR.dialog.validate.notEmpty( 'The Displayed Text field cannot be empty.' ),
required : true,
commit : function( data )
{
data.contents = this.getValue();
}
},
{
type : 'text',
id : 'url',
label : 'URL',
validate : CKEDITOR.dialog.validate.notEmpty( 'The link must have a URL.' ),
required : true,
commit : function( data )
{
data.url = this.getValue();
}
},
{
type : 'select',
id : 'style',
label : 'Style',
items :
[
[ '<none>', '' ],
[ 'Bold', 'b' ],
[ 'Underline', 'u' ],
[ 'Italics', 'i' ]
],
commit : function( data )
{
data.style = this.getValue();
}
},
{
type : 'checkbox',
id : 'newPage',
label : 'Opens in a new page',
'default' : true,
commit : function( data )
{
data.newPage = this.getValue();
}
}
]
</source>

We now have the values entered in the plugin dialog window in the <code>data</code> object. It is time to return to the <code>onOk</code> function and start building the contents of the <code>link</code> variable that contains the <code><a></code> element.

The URL of the linked page will be added to the <code><a></code> element by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setAttribute setAttribute]</code> function to update the <code>href</code> attribute of the <code>link</code> object with the contents of the <code>url</code> attribute of the <code>data</code> object.

<source lang="javascript">
link.setAttribute( 'href', data.url );
</source>

If the checkbox setting the link to open in a new page (<code>newPage</code>) was selected, we also need to set the <code>target</code> attribute of the link to <code>_blank</code> by using the <code>setAttribute</code> function again.

<source lang="javascript">
if ( data.newPage )
link.setAttribute( 'target', '_blank' );
</source>

If the user decided to apply one of the styles from the drop-down list to the link, we have to add this setting to the link element. We will use a JavaScript <code>switch</code> statement to define the style setting based on the user's choice and use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setStyle setStyle]</code> function to add an appropriate CSS stylesheet rule to the inline <code>style</code> attribute of the <code>link</code> element.

<source lang="javascript">
switch( data.style )
{
case 'b' :
link.setStyle( 'font-weight', 'bold' );
break;
case 'u' :
link.setStyle( 'text-decoration', 'underline' );
break;
case 'i' :
link.setStyle( 'font-style', 'italic' );
break;
}
</source>

We now need to insert the '''Displayed Text''' data (<code>contents</code>) into the link, in between the <code><a></code> and <code></a></code> tags. In order to achieve this we will use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setHtml setHtml]</code> function.

<source lang="javascript">
link.setHtml( data.contents );
</source>

Finally, the link object has to be inserted into the document, at the position of the cursor. We will use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#insertElement insertElement]</code> function for that.
<source lang="javascript">
editor.insertElement( link );
</source>

== Full Source Code ==
To see the full contents of the <code>plugin.js</code> file, <hide target="simpleLink_full">click here</hide>.

<note>You can also [[Media:simpleLink.zip|download the whole plugin folder]] inluding the icon and the fully commented source code.
</note>

<div id="simpleLink_full">
<source lang="javascript">
CKEDITOR.plugins.add( 'simpleLink',
{
init: function( editor )
{
editor.addCommand( 'simpleLinkDialog', new CKEDITOR.dialogCommand( 'simpleLinkDialog' ) );

editor.ui.addButton( 'SimpleLink',
{
label: 'Insert a Link',
command: 'simpleLinkDialog',
icon: this.path + 'images/icon.png'
} );

CKEDITOR.dialog.add( 'simpleLinkDialog', function( editor )
{
return {
title : 'Link Properties',
minWidth : 400,
minHeight : 200,
contents :
[
{
id : 'general',
label : 'Settings',
elements :
[
{
type : 'html',
html : 'This dialog window lets you create simple links for your website.'
},
{
type : 'textarea',
id : 'contents',
label : 'Displayed Text',
validate : CKEDITOR.dialog.validate.notEmpty( 'The Displayed Text field cannot be empty.' ),
required : true,
commit : function( data )
{
data.contents = this.getValue();
}
},
{
type : 'text',
id : 'url',
label : 'URL',
validate : CKEDITOR.dialog.validate.notEmpty( 'The link must have a URL.' ),
required : true,
commit : function( data )
{
data.url = this.getValue();
}
},
{
type : 'select',
id : 'style',
label : 'Style',
items :
[
[ '<none>', '' ],
[ 'Bold', 'b' ],
[ 'Underline', 'u' ],
[ 'Italics', 'i' ]
],
commit : function( data )
{
data.style = this.getValue();
}
},
{
type : 'checkbox',
id : 'newPage',
label : 'Opens in a new page',
'default' : true,
commit : function( data )
{
data.newPage = this.getValue();
}
}
]
}
],
onOk : function()
{
var dialog = this,
data = {},
link = editor.document.createElement( 'a' );
this.commitContent( data );

link.setAttribute( 'href', data.url );

if ( data.newPage )
link.setAttribute( 'target', '_blank' );

switch( data.style )
{
case 'b' :
link.setStyle( 'font-weight', 'bold' );
break;
case 'u' :
link.setStyle( 'text-decoration', 'underline' );
break;
case 'i' :
link.setStyle( 'font-style', 'italic' );
break;
}

link.setHtml( data.contents );

editor.insertElement( link );
}
};
});
}
});
</source>
</div>

== Working Example ==
The plugin code is now ready. When you click the '''Insert Link''' toolbar button, the custom '''Link Properties''' dialog window will open. Fill in the obligatory '''Displayed Text''' and '''URL''' fields, and click the '''OK''' button. The checkbox configuring the link to open in a new window is checked by default, but you can uncheck it. You can also change the link style by choosing one of the options from the drop-down list.

[[Image:simpleLink_example1.png|center|frame|Link added in the plugin dialog window]]

The newly added link will be inserted into the document and displayed with a style selected in the dialog window.

[[Image:simpleLink_example2.png|center|frame|Link added to the document]]

If you switched to '''Source''' view, you could see all the information from the plugin dialog window added as link contents and attributes.

[[Image:simpleLink_example3.png|center|frame|Link element shown in the Source view]]

== Further Enhancements ==
The SimpleLink plugin is now able to add a new link element to the document by using a custom and simplified dialog window, but does not make it possible to edit an already existing element by using the plugin dialog window. For tips on how to implement this feature along with the context menu support check the [[CKEditor 3.x/Tutorials/Abbr_Plugin_Part_2|Creating a Simple CKEditor Plugin, Part 2 ]] tutorial.

CKEditor 3.x/Tutorials/Abbr Plugin Part 1

2011-08-10T11:01:56Z

Fredck: /* Creating an Editor Command */

{{#CUSTOMTITLE:Creating a Simple CKEditor Plugin}}
__TOC__
The aim of this tutorial is to demonstrate how to create a basic CKEditor plugin.

We are going to develop an '''abbreviation plugin''' that lets the user insert abbreviations into their documents. The abbreviations will be using the <code>abbr</code> HTML element and will be added through a dialog window that is opened after clicking a dedicated toolbar button.

The plugin will be named <code>'''abbr'''</code>, just like the name of the corresponding HTML element that we are going to use in its implementation.

== Plugin Files ==
Firstly, we will need to create the <code>abbr</code> folder inside the <code>plugins</code> directory of the CKEditor installation.

<note>Remember that for CKEditor the name of the plugin folder is important and has to be the same as the name of the plugin, otherwise the editor will not be able to recognize it.</note>

Inside the newly created <code>abbr</code> folder we are going to place the <code>plugin.js</code> file that will contain the plugin logic. Apart from that, since we will also need a toolbar icon for our plugin, we are going to add an <code>images</code> folder and subsequently place the <code>icon.png</code> file inside.

To sum up, we will need the following file structure for our plugin to work:
* <code>''ckeditor root''</code>
** <code>plugins</code>
*** <code>abbr</code>
**** <code>images</code>
***** <code>icon.png</code>
**** <code>plugin.js</code>

== Plugin Source Code ==
With the following structure ready, it is time to open the <code>plugin.js</code> file in a text editor and to start creating the source code of the plugin.

<source lang="javascript">
CKEDITOR.plugins.add( 'abbr',
{
init: function( editor )
{
// Plugin logic goes here...
}
} );
</source>

All CKEditor plugins are created by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.resourceManager.html#add CKEDITOR.plugins.add]</code> function. This function should contain the plugin name (<code>'abbr'</code>) and the plugin logic placed inside the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.pluginDefinition.html#init init]</code> function that is called upon the initialization of the editor instance.

=== Creating an Editor Command ===
We want our plugin to have a dialog window, so we need to define an editor command that opens a new dialog window. To do this, we will need to use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#addCommand addCommand]</code> function to register the <code>abbrDialog</code> command. That command opens the <code>abbrDialog</code> dialog that we are going to define in a moment by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialogCommand.html CKEDITOR.dialogCommand]</code> class.

<source lang="javascript">
editor.addCommand( 'abbrDialog', new CKEDITOR.dialogCommand( 'abbrDialog' ) );
</source>

=== Creating a Toolbar Button ===
The plugin dialog window is to be opened by using a toolbar button. To this end, we need to define a button that will be associated with the dialog window. The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.html#addButton CKEditor.ui.addButton]</code> function accepts a button name (<code>'Abbr'</code>) along with the definition of the tooltip text (<code>label</code>) and the button icon (<code>icon</code>). Note that <code>this.path</code> is the directory where the <code>plugin.js</code> file resides.

These parameters are responsible for the button presentation. To make the button actually work, we need to connect it to the plugin command name defined above by using the <code>command</code> parameter.

<source lang="javascript">
editor.ui.addButton( 'Abbr',
{
label: 'Insert Abbreviation',
command: 'abbrDialog',
icon: this.path + 'images/icon.png'
} );
</source>

=== CKEditor Initialization ===
It is now time to initialize a CKEditor instance that will use the Abbreviation plugin along with its toolbar button.

To register the plugin with CKEditor, we have to add it to the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.extraPlugins extraPlugins]</code> list. We also need to enhance the toolbar definition and add the plugin button by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.toolbar toolbar]</code> parameter.

Open the page that will contain CKEditor in a text editor and insert a CKEditor instance using the following toolbar and plugin configuration.

<source lang="javascript">
<script type="text/javascript">
//<![CDATA[
// Replace the <textarea id="editor1"> with a CKEditor
// instance, using default configuration.
CKEDITOR.replace( 'editor1',
{
extraPlugins : 'abbr',
toolbar :
[
['Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', 'Unlink'],
['About','-','Abbr']
]
});
//]]>
</script>
</source>

After you load the page containing the above CKEditor instance, you should be able to see the new plugin toolbar button along with its tooltip.

[[Image:abbr_button_added.png|center|frame|Abbreviation plugin button added to CKEditor toolbar]]

=== Plugin Dialog Window ===
Clicking the button should open the <code>abbrDialog</code> dialog window. First, however, we need to return to the Abbreviation plugin source file and define the dialog window by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html#.add CKEDITOR.dialog.add]</code> function. To see all dialog window definition elements, refer to the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html CKEditor JavaScript API].

In our case we will give the dialog window a name (<code>'abbrDialog'</code>) and use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#title title]</code>, <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#minWidth minWidth]</code>, and <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#minHeight minHeight]</code> parameters to define its title and minimum dimensions, respectively.

<note>The name selected for the dialog window is the name that appears in the <code>addCommand</code> function above.
</note>

==== Dialog Window Tabs ====
The dialog window should also contain some [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#contents contents], so we will begin with [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.contentDefinition.html adding] two tabs along with their labels. Note that by default CKEditor also adds the standard '''OK''' and '''Cancel''' buttons.

In order to create the Abbreviation plugin dialog window along with two tabs, add the following code in the <code>plugin.js</code> file below the plugin toolbar button definition.
<source lang="javascript">
CKEDITOR.dialog.add( 'abbrDialog', function ( editor )
{
return {
title : 'Abbreviation Properties',
minWidth : 400,
minHeight : 200,

contents :
[
{
id : 'tab1',
label : 'Basic Settings',
elements :
[
// UI elements of the first tab will be defined here
]
},
{
id : 'tab2',
label : 'Advanced Settings',
elements :
[
// UI elements of the second tab will be defined here
]
}
]
};
} );
</source>
The result of this change can be seen immediately. Click the '''Insert Abbreviation''' toolbar button in order to open the newly created '''Abbreviation Properties''' dialog window containing two (empty) tabs.

[[Image:abbr_empty_tabs.png|center|frame|A plugin dialog window with two tabs added]]

==== Dialog Window Tabs Elements ====
User interface elements that can be added to a dialog window tab are defined in the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.contentDefinition.html#elements elements]</code> parameter, which is an array of <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.uiElementDefinition.html CKEDITOR.dialog.uiElementDefinition]</code> objects.

The '''Basic Settings''' tab will contain two mandatory text fields (<code>type : 'text'</code>) with the abbreviation and its explanation. Since both fields are obligatory, it is useful to add a simple validation mechanism in order to ensure that the user fills them.

The '''Advanced Settings''' tab will contain a single optional text field that allows the user to assign an <code>id</code> to the abbreviation element.

The code snippet presented below shows a full definition of the contents of both plugin tabs.
<source lang="javascript">
contents :
[
{
id : 'tab1',
label : 'Basic Settings',
elements :
[
{
type : 'text',
id : 'abbr',
label : 'Abbreviation',
validate : CKEDITOR.dialog.validate.notEmpty( "Abbreviation field cannot be empty" )
},
{
type : 'text',
id : 'title',
label : 'Explanation',
validate : CKEDITOR.dialog.validate.notEmpty( "Explanation field cannot be empty" )
}
]
},
{
id : 'tab2',
label : 'Advanced Settings',
elements :
[
{
type : 'text',
id : 'id',
label : 'Id'
}
]
}
]
</source>

When you reload the editor instance and open the '''Abbreviation Properties''' dialog window, the '''Basic Settings''' tab will now contain two mandatory text fields.

[[Image:abbr_basic_settings_tab.png|center|frame|Basic Settings tab of the Abbreviation plugin]]

The '''Advanced Settings''' tab only contains a single <code>id</code> text field that can be left empty.

[[Image:abbr_advanced_settings_tab.png|center|frame|Advanced Settings tab of the Abbreviation plugin]]

=== Plugin Behavior ===
The presentation layer of the plugin is now ready, so we can define the plugin behavior to actually make it work.

The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#onOk onOk]</code> method is invoked once the user accepts the changes introduced in the dialog window by clicking the '''OK''' button or pressing the ''Enter'' key on the keyboard. Since the plugin adds a new <code>abbr</code> element to the DOM tree, we can use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.document.html#createElement createElement]</code> function to create a new DOM element.

With the new DOM element created, we can now retrieve the values of the <code>title</code> and (optional) <code>id</code> fields with the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html#getValueOf getValueOf]</code> function and pass them to appropriate <code>abbr</code> element attributes by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setAttribute setAttribute]</code> function.

Finally, we will pass the text entered in the <code>abbr</code> text field as the contents of the <code>abbr</code> element by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setText setText]</code> function.

With the contents of the <code>abbr</code> element ready, we can insert it into the document at the location of the cursor by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#insertElement insertElement]</code> function.

Add the following <code>onOk</code> function code to your dialog window definition, below the code that creates the contents of the dialog.

<source lang="javascript">
onOk : function()
{
var dialog = this;
var abbr = editor.document.createElement( 'abbr' );

abbr.setAttribute( 'title', dialog.getValueOf( 'tab1', 'title' ) );
abbr.setText( dialog.getValueOf( 'tab1', 'abbr' ) );

var id = dialog.getValueOf( 'tab2', 'id' );
if ( id )
abbr.setAttribute( 'id', id );

editor.insertElement( abbr );
}
</source>

<note>Please note that another way to insert HTML code into CKEditor is using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#insertHtml insertHtml]</code> function that adds HTML code at the location of the cursor in the document.

<source lang="javascript">
editor.insertHtml( '<h2>This is a sample header</h2><p>This is a sample paragraph.</p>' );
</source>
</note>

== Full Source Code ==
To see the full contents of the <code>plugin.js</code> file, <hide target="abbr_full">click here</hide>.

<note>You can also [[Media:abbr.zip|download the whole plugin folder]] inluding the icon and the fully commented source code.
</note>

<div id="abbr_full">
<source lang="javascript">
CKEDITOR.plugins.add( 'abbr',
{
init: function( editor )
{
editor.addCommand( 'abbrDialog',new CKEDITOR.dialogCommand( 'abbrDialog' ) );
editor.ui.addButton( 'Abbr',
{
label: 'Insert Abbreviation',
command: 'abbrDialog',
icon: this.path + 'images/icon.png'
} );
CKEDITOR.dialog.add( 'abbrDialog', function( editor )
{
return {
title : 'Abbreviation Properties',
minWidth : 400,
minHeight : 200,
contents :
[
{
id : 'tab1',
label : 'Basic Settings',
elements :
[
{
type : 'text',
id : 'abbr',
label : 'Abbreviation',
validate : CKEDITOR.dialog.validate.notEmpty( "Abbreviation field cannot be empty" )
},
{
type : 'text',
id : 'title',
label : 'Explanation',
validate : CKEDITOR.dialog.validate.notEmpty( "Explanation field cannot be empty" )
}
]
},
{
id : 'tab2',
label : 'Advanced Settings',
elements :
[
{
type : 'text',
id : 'id',
label : 'Id'
}
]
}
],
onOk : function()
{
var dialog = this;

var abbr = editor.document.createElement( 'abbr' );
abbr.setAttribute( 'title', dialog.getValueOf( 'tab1', 'title' ) );
abbr.setText( dialog.getValueOf( 'tab1', 'abbr' ) );
var id = dialog.getValueOf( 'tab2', 'id' );
if ( id )
abbr.setAttribute( 'id', id );
editor.insertElement( abbr );
}
};
} );
}
} );
</source>
</div>

== Working Example ==
The plugin code is now ready. When you click the '''Insert Abbreviation''' toolbar button, the '''Abbreviation Properties''' dialog window will open. Fill in the obligatory '''Abbreviation''' and '''Explanation''' fields and click the '''OK''' button.

[[Image:abbr_example1.png|center|frame|Abbreviation added in the dialog window]]

The newly added abbreviation will be inserted into the document and will be displayed using the default styling of your browser. In Firefox, for example, the abbreviation will be underlined using a dotted line and the explanation will be displayed in a tooltip.

[[Image:abbr_example2.png|center|frame|Abbreviation added in the dialog window]]

== Further Enhancements ==
The Abbreviation plugin is now able to add a new <code>abbr</code> element to the document, but does not make it possible to edit an already existing element. For this feature along with the context menu support check the [[CKEditor 3.x/Tutorials/Abbr_Plugin_Part_2|second part of the tutorial]].

Talk:CKEditor 3.x/Howto/Default Field Values

2011-02-14T19:53:17Z

Fredck: Title is misleading

== Title is misleading ==

The page title, "How Do I Set a Default Value for a CKEditor Dialog Window Field?", is misleading. When looking at the HOWTOs list, I understood that it would explain how to set the default value of '''existing dialogs'''. But instead it talks about '''custom''' dialogs.

Maybe "How Do I Set a Default Value for a '''Custom''' CKEditor Dialog Window Field?"? --[[User:Fredck|FredCK]] 19:53, 14 February 2011 (UTC)

CKEditor 3.x/Developers Guide/Data Processor

2010-10-20T15:32:39Z

Fredck: /* HTML Parser Filters */

{{#CUSTOMTITLE:Data Processor: Data Input and Output Manipulation}}CKEditor is a '''browser based''' editor. It means it uses the browser infrastructure to create its editing environment. Because of this the editing area in the editor is simply an HTML page that's manipulated by the user by typing or by using the editor features. Technically speaking, CKEditor is performing [http://en.wikipedia.org/wiki/Document_Object_Model DOM] manipulation on the page contents.

Even if CKEditor uses HTML and the browser DOM as its base for editing, it is possible to input and output any kind of data on it. This data transformation is handled by the so called "Data Processor".

== The Data Processor ==

The Data Processor is an object, in the JavaScript point of view, which transforms the input data into HTML, and back to the output data format later. This transformation is provided by the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dataProcessor.html#toHtml toHtml] and [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dataProcessor.html#toDataFormat toDataFormat] functions, respectively.

[[File:CKEditor_Data_Processor.png]]

== The Default Data Processor: XHTML ==

CKEditor is distributed with an XHTML Data Processor. This may sound strange, but it transforms the (X)HTML data inputted in the editor into "good" HTML. In this process it also makes some transformations required by some of the editor features.

The XHTML Data Processor is quite a complex, and flexible, piece of program. It's composed by several parts:

[[File:CKEditor_XHTML_Data_Processor.png]]

* HTML Parser: reads the HTML inputted in the editor, transforming it into "good" html. It also transforms the HTML string into a JavaScript object tree, to be manipulated by "filters". See [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.htmlParser.html CKEDITOR.htmlParser].

* HTML Writer: outputs strings in HTML format based on the object tree representation of the data.
Note that the HTML Parser is used on output as well, when retrieving the HTML from the browser. This is needed because browsers, especially IE, may produce bad quality code.

The default Data Processor can be retrieved and manipulated by the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#dataProcessor editor.dataProcessor] property.

== HTML Parser Filters ==

Filters are one of the powerful features available on the HTML Parser. They're applied to the object representation of the parsed HTML data when transforming it back to strings.

Some of the application of filters are:

* Remove attributes from elements.
* Rewrite elements attributes values.
* Rename element names or attributes.
* Add missing attributes to elements.
* Etc...

The default XHTML Data Processor already applies several filters either on input and on output of data. You can extend it by adding custom filter rules (calling addRules()) to the following objects:

* editor.dataProcessor.dataFilter: filter applied to the input data when transforming it to HTML to be loaded into the editor ("on input").
* editor.dataProcessor.htmlFilter: filter applied to the HTML available in the editor when transforming it on the XHTML outputted by the editor ("on output").

For example, the following code will ensure that <img> elements will have their "alt" attribute filled:

<pre>
editor.dataProcessor.htmlFilter.addRules(
{
elements :
{
img : function( element )
{
if ( !element.attributes.alt )
element.attributes.alt = 'An image';
}
}
});
</pre>

== Custom Data Processors ==

Plugin implementers can create data processors, which can transform custom non HTML data formats to be loaded and outputted by the editor. For example, there could be data processors for [http://en.wikipedia.org/wiki/BBCode BBCode], [http://en.wikipedia.org/wiki/Wiki_markup Wiki markup], or any other kind of structured data markup. Even server side transformation could be considered, by executing [http://en.wikipedia.org/wiki/XMLHttpRequest Ajax style calls] from the data processor code.

To make the editor use a custom data processor, it's enough to set [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#dataProcessor editor.dataProcessor] to an object implementing the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dataProcessor.html data processor interface], replacing the default XHTML Data Processor.

Custom data processors may use parts of the default XHTML Data Processor code, including the HTML Parser or even the HTML Writer. It's recommended checking the [http://dev.ckeditor.com/browser/CKEditor/trunk/_source/plugins/htmldataprocessor/plugin.js htmldataprocessor plugin code] for reference and ideas.

CKEditor 3.x/Developers Guide/Data Processor

2010-10-20T15:24:40Z

Fredck:

{{#CUSTOMTITLE:Data Processor: Data Input and Output Manipulation}}CKEditor is a '''browser based''' editor. It means it uses the browser infrastructure to create its editing environment. Because of this the editing area in the editor is simply an HTML page that's manipulated by the user by typing or by using the editor features. Technically speaking, CKEditor is performing [http://en.wikipedia.org/wiki/Document_Object_Model DOM] manipulation on the page contents.

Even if CKEditor uses HTML and the browser DOM as its base for editing, it is possible to input and output any kind of data on it. This data transformation is handled by the so called "Data Processor".

== The Data Processor ==

The Data Processor is an object, in the JavaScript point of view, which transforms the input data into HTML, and back to the output data format later. This transformation is provided by the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dataProcessor.html#toHtml toHtml] and [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dataProcessor.html#toDataFormat toDataFormat] functions, respectively.

[[File:CKEditor_Data_Processor.png]]

== The Default Data Processor: XHTML ==

CKEditor is distributed with an XHTML Data Processor. This may sound strange, but it transforms the (X)HTML data inputted in the editor into "good" HTML. In this process it also makes some transformations required by some of the editor features.

The XHTML Data Processor is quite a complex, and flexible, piece of program. It's composed by several parts:

[[File:CKEditor_XHTML_Data_Processor.png]]

* HTML Parser: reads the HTML inputted in the editor, transforming it into "good" html. It also transforms the HTML string into a JavaScript object tree, to be manipulated by "filters". See [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.htmlParser.html CKEDITOR.htmlParser].

* HTML Writer: outputs strings in HTML format based on the object tree representation of the data.
Note that the HTML Parser is used on output as well, when retrieving the HTML from the browser. This is needed because browsers, especially IE, may produce bad quality code.

The default Data Processor can be retrieved and manipulated by the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#dataProcessor editor.dataProcessor] property.

== HTML Parser Filters ==

Filters are one of the powerful features available on the HTML Parser. They're applied to the object representation of the parsed HTML data when transforming it back to strings.

Some of the application of filters are:

* Remove attributes from elements.
* Rewrite elements attributes values.
* Rename element names or attributes.
* Add missing attributes to elements.
* Etc...

The default XHTML Data Processor already applies several filters either on input and on output of data. You can extend it by adding custom filter rules (calling addRules()) to the following objects:

* editor.dataProcessor.dataFilter: filter applied to the input data when transforming it to HTML to be loaded into the editor ("on input").
* editor.dataProcessor.htmlFilter: filter applied to the HTML available in the editor when transforming it on the XHTML outputted by the editor ("on output").

For example, the following code will ensure that <img> elements will have their "alt" attribute filled:

<pre>
editor.dataProcessor.htmlFilter.addRules(
{
elements :
{
img : function( element )
{
if ( !element.attributes.alt )
elements.attributes.alt = 'An image';
}
}
});
</pre>

== Custom Data Processors ==

Plugin implementers can create data processors, which can transform custom non HTML data formats to be loaded and outputted by the editor. For example, there could be data processors for [http://en.wikipedia.org/wiki/BBCode BBCode], [http://en.wikipedia.org/wiki/Wiki_markup Wiki markup], or any other kind of structured data markup. Even server side transformation could be considered, by executing [http://en.wikipedia.org/wiki/XMLHttpRequest Ajax style calls] from the data processor code.

To make the editor use a custom data processor, it's enough to set [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#dataProcessor editor.dataProcessor] to an object implementing the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dataProcessor.html data processor interface], replacing the default XHTML Data Processor.

Custom data processors may use parts of the default XHTML Data Processor code, including the HTML Parser or even the HTML Writer. It's recommended checking the [http://dev.ckeditor.com/browser/CKEditor/trunk/_source/plugins/htmldataprocessor/plugin.js htmldataprocessor plugin code] for reference and ideas.

CKEditor 3.x/Developers Guide/Data Processor

2010-10-20T15:23:30Z

Fredck: Created page with 'CKEditor is a '''browser based''' editor. It means it uses the browser infrastructure to create its editing environment. Because of this the editing area in the editor is simply …'

CKEditor is a '''browser based''' editor. It means it uses the browser infrastructure to create its editing environment. Because of this the editing area in the editor is simply an HTML page that's manipulated by the user by typing or by using the editor features. Technically speaking, CKEditor is performing [http://en.wikipedia.org/wiki/Document_Object_Model DOM] manipulation on the page contents.

Even if CKEditor uses HTML and the browser DOM as its base for editing, it is possible to input and output any kind of data on it. This data transformation is handled by the so called "Data Processor".

== The Data Processor ==

The Data Processor is an object, in the JavaScript point of view, which transforms the input data into HTML, and back to the output data format later. This transformation is provided by the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dataProcessor.html#toHtml toHtml] and [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dataProcessor.html#toDataFormat toDataFormat] functions, respectively.

[[File:CKEditor_Data_Processor.png]]

== The Default Data Processor: XHTML ==

CKEditor is distributed with an XHTML Data Processor. This may sound strange, but it transforms the (X)HTML data inputted in the editor into "good" HTML. In this process it also makes some transformations required by some of the editor features.

The XHTML Data Processor is quite a complex, and flexible, piece of program. It's composed by several parts:

[[File:CKEditor_XHTML_Data_Processor.png]]

* HTML Parser: reads the HTML inputted in the editor, transforming it into "good" html. It also transforms the HTML string into a JavaScript object tree, to be manipulated by "filters". See [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.htmlParser.html CKEDITOR.htmlParser].

* HTML Writer: outputs strings in HTML format based on the object tree representation of the data.
Note that the HTML Parser is used on output as well, when retrieving the HTML from the browser. This is needed because browsers, especially IE, may produce bad quality code.

The default Data Processor can be retrieved and manipulated by the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#dataProcessor editor.dataProcessor] property.

== HTML Parser Filters ==

Filters are one of the powerful features available on the HTML Parser. They're applied to the object representation of the parsed HTML data when transforming it back to strings.

Some of the application of filters are:

* Remove attributes from elements.
* Rewrite elements attributes values.
* Rename element names or attributes.
* Add missing attributes to elements.
* Etc...

The default XHTML Data Processor already applies several filters either on input and on output of data. You can extend it by adding custom filter rules (calling addRules()) to the following objects:

* editor.dataProcessor.dataFilter: filter applied to the input data when transforming it to HTML to be loaded into the editor ("on input").
* editor.dataProcessor.htmlFilter: filter applied to the HTML available in the editor when transforming it on the XHTML outputted by the editor ("on output").

For example, the following code will ensure that <img> elements will have their "alt" attribute filled:

<pre>
editor.dataProcessor.htmlFilter.addRules(
{
elements :
{
img : function( element )
{
if ( !element.attributes.alt )
elements.attributes.alt = 'An image';
}
}
});
</pre>

== Custom Data Processors ==

Plugin implementers can create data processors, which can transform custom non HTML data formats to be loaded and outputted by the editor. For example, there could be data processors for [http://en.wikipedia.org/wiki/BBCode BBCode], [http://en.wikipedia.org/wiki/Wiki_markup Wiki markup], or any other kind of structured data markup. Even server side transformation could be considered, by executing [http://en.wikipedia.org/wiki/XMLHttpRequest Ajax style calls] from the data processor code.

To make the editor use a custom data processor, it's enough to set [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#dataProcessor editor.dataProcessor] to an object implementing the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dataProcessor.html data processor interface], replacing the default XHTML Data Processor.

Custom data processors may use parts of the default XHTML Data Processor code, including the HTML Parser or even the HTML Writer. It's recommended checking the [http://dev.ckeditor.com/browser/CKEditor/trunk/_source/plugins/htmldataprocessor/plugin.js htmldataprocessor plugin code] for reference and ideas.

File:CKEditor XHTML Data Processor.png

2010-10-20T15:06:12Z

Fredck: uploaded a new version of "File:CKEditor XHTML Data Processor.png": Reduced the image width.

File:CKEditor XHTML Data Processor.png

2010-10-20T15:00:08Z

Fredck:

File:CKEditor Data Processor.png

2010-10-20T14:57:48Z

Fredck:

CKEditor 3.x/Developers Guide

2010-10-20T14:46:29Z

Fredck: Added Data Processor

{{#CUSTOMTITLE:CKEditor 3.x - Developer's Guide}}

*[[CKEditor 3.x/Developers Guide/Installation|Installation]]
* Integration
**[[CKEditor 3.x/Developers Guide/Integration|Integration]]
** [[CKEditor 3.x/Developers Guide/jQuery Adapter|jQuery]]
*Configuration
**[[CKEditor 3.x/Developers Guide/Setting Configurations|Setting Configurations]]
**[[CKEditor 3.x/Developers Guide/Toolbar|Toolbar]]
**[[CKEditor_3.x/Developers_Guide/Styles|Styles]]
**[[CKEditor 3.x/Developers Guide/Output Formatting|Output Formatting]]
**[[CKEditor 3.x/Developers Guide/Templates|Templates]]
**Spell Checker
**[[CKEditor 3.x/Developers Guide/File Browser (Uploader)|File Browser/Uploader ]]
*Customization
**[[CKEditor 3.x/Developers Guide/Dialog_Customization|Dialogs]]
**Plugins
**Skins
*Advanced Tasks
**[[CKEditor_3.x/Developers_Guide/Editor_Core_URLs_Manipulation|Editor Core URLs Manipulation]]
**[[CKEditor_3.x/Developers_Guide/Data_Processor|Data Processor: Data Input and Output Manipulation]]
*Deployment
*[http://docs.cksource.com/ckeditor_api/ JavaScript API]
*[[FCKeditor 3.x/Design and Architecture|Design and Architecture]]

FCKeditor 3.x/Design and Architecture/Coding Patterns

2010-09-13T14:44:52Z

Fredck:

This page lists some interesting coding patterns that we may or may not use in our code.

== Self Executing Functions ==

This is already a classic. Using a self calling function declaration to isolate its contents from the current scope, avoiding polluting it with variables.

<pre>
(function()
{
...
})();
</pre>

== Objects with Private Stuff ==

<pre>
var myObj = function()
{
// Private variables.
var privateVar = 10;

var privateFunction = function()
{
...
};

// Public stuff.
return {
publicMethod : function()
{
// May access privateVar or privateFunction.
...
}
};
}();
</pre>

== For Loops and Length ==

The "length" property should not be checked on each "for" cycle. The following construction should be used instead:

<pre>
for ( var i = 0, len = list.length ; i < len ; i++ }
{
...
}
</pre>

FCKeditor 3.x/Design and Architecture/Coding Style

2010-09-13T14:43:11Z

Fredck: Added String Literals

= Coding Style Guidelines =

These guidelines where defined based on mixed common standards mainly related to Java programming. It aims to reflect the generally accepted standards for JavaScript coding with some minor adjustments.

It is quite common to take the Java style to write JavaScript code, assuming it is a "cut-down" version of Java. Although JavaScript has an indirect relation with Java, apart from the similar "C
== General Recommendations ==

Any violation to the guide is allowed if it enhances readability.

If the name "CKEditor" is used, if must always be written with "CKE" uppercased concatenated with "ditor" in lowercase. The following usages are wrong: "CKeditor", "ckEditor", "CK Editor", etc. Exceptions are made for directories and file names, which must always be lowercased, and the CKEDITOR namespace name.

If the name "FCKeditor" is used, it must always be written with "FCK" uppercased concatenated with "editor" in lowercase. The following are wrong: "FckEditor", "FCKEditor", "fckEditor", "FCK Editor", and so on. Exception is made for directory names, where all chars "should" be in lowercase.

The name "JavaScript" should be written with both the "J" and "S" in uppercase. The following are wrong: "Javascript", "javascript", etc.

== Naming Conventions ==

=== Generic Name Conventions ===

The ROOT namespace has a fixed name: CKEDITOR.
<pre>CKEDITOR
</pre>
Names representing namespaces must be all lowercase.
<pre>CKEDITOR.dom, CKEDITOR.env, CKEDITOR.ui
</pre>
Names representing public classes and public global objects must be in PascalCase.
<pre>CKEDITOR.dom.Document, CKEDITOR.Util
</pre>
Names representing constants must be all UPPERCASE.
<pre>CKEDITOR.STATUS_COMPLETE, CKEDITOR.EDITMODE_WYSIWYG, CKEDITOR.CTRL
</pre>
Names representing public methods must be verbs and written in camelCase.
<pre>appendStyleSheet(), getElement (), setTimeout()
</pre>
Names representing public properties must be nouns and written in camelCase.
<pre>name, document, targetWindow
</pre>
Names representing private methods must be verbs and written in camelCase prefixed with an underscore.
<pre>_doInternalStuff()
</pre>
Names representing private properties must be nouns and written in camelCase prefixed with an underscore.
<pre>_internalCounter, _prefix
</pre>
Abbreviations and acronyms should not be uppercase when used as name.
<pre>setHtml(), XmlDocument
NOT
setHTML(), XMLDocument
</pre>
All names should be written in English.

=== Specific Name Conventions ===

The prefixes "get" and "set" may be used on methods that get or set properties which require computation.
<pre>setArrayCount(), getFormattedValue()
</pre>
The prefix "checkIs" may be used on methods which return boolean states which require computation.
<pre>checkIsValid(), checkIsEmpty()
</pre>
Abbreviations in names should be avoided.
<pre>getDirectoryName(), applicationCommand
NOT
getDirName(), appCmd
</pre>
== Files ==

All files must be named in all lower case.

Classes and global objects should be declared in individual files with the file name matching the class/object name.
<pre>fckbrowserinfo.js, fcktoolbarbutton.js
</pre>
== Layout ==

For indentation, the TAB should be used. Development IDEs should be configured to represent TABs as 4 spaces.
<pre>if ( test )
{
if ( otherTest )
doSomething();
doMore();
}
</pre>
Block layout should be as illustrated.
<pre>while ( !done )
{
doSomething();
done = moreToDo();
}
</pre>
Single statement (single line only) if/else/while/for could (preferably) be written without brackets, but never in the same line.
<pre>if ( condition )
statement;

while ( condition )
statement;

for ( initialization ; condition ; update )
statement;
</pre>
The above rule is not valid for nested blocks, like the following:
<pre>if ( condition )
{
if ( anotherCondition )
statement;
}

// WRONG:
if ( condition )
if ( anotherCondition )
statement;
</pre>
The incompleteness of split lines must be made obvious.
<pre>totalSum = a + b + c +
d + e;

method( param1, param2,
param3 );

setText( 'Long line split' +
'into two parts.' );
</pre>
=== Whitespace ===
"If", "for", "while" and "switch" should be followed by a white space.
<pre>if ( true )
NOT
if( true )
</pre>
Conventional operators should be surrounded by a space (including ternary operators).
<pre>if ( i > 3 && test == 'yes' )
</pre>
Commas should be followed by a space.
<pre>function myFunction( parm1, param2, param3 )
</pre>
Semi-colons in for statements should be surrounded by a space.
<pre>for ( var i = 0 ; i < count ; i++ )
</pre>
Semi-colons should not be preceded by a space.
<pre>doSomething();
var name = 'John';
</pre>
Colons should be surrounded by a space.
<pre>case 100 :
NOT
case 100:
</pre>
Opening parenthesis must be followed by a space and closing parenthesis must be preceded by a space.
<pre>if ( myVar == 1 )
</pre>
There special cases where no space is recommended. When opening parenthesis for a "self-executing anonymous function" and when closing parenthesis after an indented code block:
<pre>(function()
{
// Code here
})();

myMethod( function()
{
// Code here
});
</pre>
Functions/method calls should not be followed by a space.
<pre>doSomething( someParameter );
NOT
doSomething ( someParameter );
</pre>
Logical units within a block should be separated by one blank line.
<pre>// Create a new identity matrix
var matrix = new Matrix4x4();

// Precompute angles for efficiency
var cosAngle = mathCos( angle );
var sinAngle = mathSin( angle );

// Specify matrix as a rotation transformation
matrix.setElement( 1, 1, cosAngle );
matrix.setElement( 1, 2, sinAngle );
matrix.setElement( 2, 1, -sinAngle );
matrix.setElement( 2, 2, cosAngle );

// Apply rotation
transformation.multiply( matrix );
</pre>

Multiple variables declaration in a single "var" statement must be aligned with a single tab.

<pre>
var example = 1,
sample = 2;
NOT
var example = 1,
sample = 2;
</pre>

== Variables ==

Variables must be always defined with "var".

Function parameters must be in camelCase.
<pre>function sum( firstNumber, secondNumber )
</pre>
Local variables must be in camelCase.
<pre>function doSomething()
{
var colorOne = 1;
var colorTwo = 2;

return colorOne + colorTwo;
}
</pre>
Several variables can be defined with a single var statement, but only if their initialization values are in single lines. Do not initialize more than one variable is a single line:
<pre>var aVar, someVar,
other1Var = 10,
other2Var = 25,
isVar = true;

var longVar = function()
{
// This var takes more than one line.
};

var objVar =
{
// This var takes more than one line.
};
</pre>

== Comments ==

Tricky code should not be commented but rewritten: In general, the use of comments should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure.

All comments should be written in English. Whenever possible, end comments with a period as normal phrases, and wrap comments within the first 80 characters of each line.

There should be a space after the comment identifier.
<pre>// This is a comment. NOT: //This is a comment
/** NOT: /**
* This is block *This is a block
* comment. *comment
*/ */
</pre>
Note that comment blocks should be opened with two asterisks only for documentation purposes. See [[FCKeditor 3.x/Design and Architecture/Documentation#JavaScript_API|JavaScript API Documentation]].

== Regular Expressions ==

The '''regular expression literal''' should be used whenever possible, instead of the RegExp object, which should be used only when the regular expression pattern is not constant or depends on runtime computation.
<pre>/^foo\s*/i
NOT
new RegExp( '^foo\s*', 'i' )
</pre>
Other than shortnesses and better readability, regular expression literals are compiled during script evaluation, which improves performance at runtime.

== String Literals ==

When defining string literals, use single quotes instead of double quotes, whenever possible.

<pre>var s = 'Some text';
NOT
var s = "Some text";
</pre>

== File Headers ==

There are minimum requirements for us to be able to make our code available to the world. Most of them are related to legal needs, which help us protecting the project from abuses.

Here is a JavaScript template for the header to be included in the source code:
<pre>/*
Copyright (c) 2003-2009, CKSource - Frederico Knabben. All rights reserved.
For licensing, see LICENSE.html or http://ckeditor.com/license
*/
</pre>
Of course, different languages have different commenting syntax, so it is enough to copy the header from an existing file to maintain the style.

=== Author Tags ===

Author names, e-mails or web site addresses should be avoided in the header. To justify that, let me recall a citation from Sander Striker, a member of the Apache Software Foundation, that can be found at [http://producingoss.com/en/managing-volunteers.html#territoriality Producing Open Source Software]:
<blockquote>At the Apache Software foundation we discourage the use of author tags in source code. There are various reasons for this, apart from the legal ramifications. Collaborative development is about working on projects as a group and caring for the project as a group. Giving credit is good, and should be done, but in a way that does not allow for false attribution, even by implication. There is no clear line for when to add or remove an author tag. Do you add your name when you change a comment? When you put in a one-line fix? Do you remove other author tags when you refactor the code and it looks 95% different? What do you do about people who go about touching every file, changing just enough to make the virtual author tag quota, so that their name will be everywhere?<br> </blockquote> <blockquote>
There are better ways to give credit, and our preference is to use those. From a technical standpoint author tags are unnecessary; if you wish to find out who wrote a particular piece of code, the version control system can be consulted to figure that out. Author tags also tend to get out of date. Do you really wish to be contacted in private about a piece of code you wrote five years ago and were glad to have forgotten?<br>
</blockquote>
The SVN is a good place to understand user participation. Even when committing changes proposed by Joe White, it is nice to add a comment like "Thanks to Joe White." in the commit message.

Talk:CKEditor 3.x/

2010-07-09T08:28:42Z

Fredck:

Any hope of making editable stub pages for some of the topics in this table of contents? That way, people with validated accounts would be able to help edit them. --[[User:Akjohnson|Akjohnson]] 03:02, 4 July 2010 (UTC)

- We've tried it in the past, with bad results: vandalism, low quality, anarchy, etc. So for now, contributions can be placed in the talk pages directly. --[[User:Fredck|FredCK]] 08:28, 9 July 2010 (UTC)

Talk:CKEditor 3.x/

2010-07-09T08:28:19Z

Fredck:

Talk:FCKeditor 3.x/Design and Architecture/Dialog System

2010-06-03T10:00:27Z

Fredck: Blanked the page

FCKeditor 3.x/Design and Architecture/Dialog System

2010-06-03T09:59:37Z

Fredck: /* Dialog Definition */

The new dialog system in CKEditor is to be written from scratch. One of the key things in CKEditor is that it doesn't rely on HTML pages to run. Everything is created on the fly in JavaScript. In this way, we avoid limitations about cross domain serving of the editor code, like CDN solutions, and enhance the editor performance.

== Framework ==

Dialogs will be controlled by the Dialog System Framework. This system offer features to define, modify and use dialogs within the editor. It brings uniform design among the dialogs, as well as advanced features with easy.

== Dialog Manager ==

The Dialog Manager is the core of the dialog system. It introduces API features to open and manage dialogs in the editor. It also creates the basic structure of the dialog, the dialog framework, and loads the dialog contents. It manages dialog contents validation and provides the features to be used by the dialog definition object.

== Main API ==

The dialog system runs under the CKEDITOR.dialog namespace. Its code is to be defined in the "dialog" plugin.

The dialog plugin extends the CKEDITOR.editor class, by adding the "'''CKEDITOR.editor.openDialog'''" function. This function is relative to the editor instance, because dialogs are sensitive to its configurations, as well as to its contents and selection state.

== Structure ==

In a macro structure definition, a dialog is composed by the following pieces:

*'''Cover''': a semi transparent element which is placed over the entire page to give the user a "modal dialog" effect. The user is required to close the dialog to access the page again.

*'''Main Dialog Structure''': a floating element that holds the dialog structure. This structure defines several elements that are common to all dialogs:<br>
**'''Title''': a title space for the dialog.
**'''Close button''': an element that closes the dialog on click.
**'''Buttons space''': a space reserved to the main dialog buttons, like the "OK" and "Cancel" buttons.
**'''Resize handle''': the element to be used to resize the dialog, if resizable.
**'''Contents''': the space where the dialog contents are to be rendered.
**'''Tabs Space''': the space where dialog tabs are to be rendered. Each tab fills the Contents space with different contents.

The following is a sample graphical representation of this structure:
<pre>+---------------------------------------+
| (Cover) |
| +---------------------------+ |
| | (Title) (x) | |
| |---------------------------| |
| | (Tabs) | |
| |---------------------------| |
| | (Contents) | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| |---------------------------| |
| | (Buttons) (/)| |
| +---------------------------+ |
| |
+---------------------------------------+

(x) = Close button
(/) = Resize handle
</pre>
The main dialog structure is defined by the editor theme, by its "buildDialog" function. This function returns the HTML for the main dialog structure, as well as the information needed by the dialog system to render it properly and fill its "placeholders".

== Dialog Definition ==

When opening a dialog, the "Dialog Definition" is to be passed to the dialog system. This definition must be first "registered", to be then called later. The following function can be used to register it:
<pre>CKEDITOR.dialog.add( 'dialog name', function( editor )
{
return { ... definition ... };
});

or

CKEDITOR.dialog.add( 'dialog name', 'definition file path.js' );
</pre>
Note that the definition can either be passed to the dialog system directly, or even be found in a separated JavaScript file. The dialog system will then use a callback system to download the file and load the definition. The definition file should have the add() function call to register the dialog again, just like the first of the above examples. The definitions are then cached and reused by all editor instances.

The definition is a function that receives an editor instance. This function is called every time a dialog is to be displayed. It then returns the definition object, which may be customized for that specific instance. The following is a compact representation of this object:
<pre>{
title: 'Dialog Title',

resizable: CKEDITOR.DIALOG_RESIZE_NONE,

minWidth: {number},

minHeight: {number},

buttons: [ ... ],

contents: [ ... ],

onOk: function() { ... },

onCancel: function() { ... },

onLoad: function( data ) { ... }
}
</pre>
Only the "title" and "contents" properties are required. Other properties have their default values.

Plugins or user code may at any time change the dialog definition, adding or removing things from it. It is enough to listen for the "dialogDefinition" event in the CKEDITOR object. The definition can also be retrieved at any time after it with the CKEDITOR.dialog.get function.

Dialogs are not resizable by default. If any of the resize constants are defined (CKEDITOR.DIALOG_RESIZE_HEIGHT | CKEDITOR.DIALOG_RESIZE_WIDHT | CKEDITOR.DIALOG_RESIZE_BOTH), the resize handle will be displayed. The size of the "contents" placeholder is changed when resizing, and the minWidth and minHeight properties are respected.

The "onOk" and "onCancel" are properties that can be set to functions to be called when one of the standard buttons is clicked. If the function explicitly returns "false", the dialog don't get closed.

The "onLoad" function is called when the dialog is loaded. An empty "data" object is passed to it. This object may get filled by the function with data to be reused by the dialog elements.

=== Buttons Definition ===

By default, the "Cancel" button is available on dialogs. The definition can instead contain a list of buttons to be displayed. The following is an example of the buttons property definition:
<pre>buttons: [
CKEDITOR.dialog.okButton,

CKEDITOR.dialog.cancelButton,

{
id: 'unique name',
type: 'button',
label: 'Custom Button',
title: 'Button description',
accessKey: 'C',
disabled: false,
onClick: function()
{
// code on click
},
}
]
</pre>
Note that special objects are available for the "Ok" and "Cancel" buttons. Those objects are actually functions, which accept an object that overrides their default properties. For example, if you want the "Ok" button to be labeled "Go", just do this:
<pre>buttons: [
CKEDITOR.dialog.okButton( {
label: 'Go'
}),

CKEDITOR.dialog.cancelButton
]
</pre>
The "id" property can be defined on custom buttons. It makes it possible to retrieve a specific button at runtime to execute special functions on it, like enabling/disabling it, or even triggering its click.

We encourage defining an access key for each custom button. It should be a keyboard keystroke, which will be then combined with the CTRL key. The Ok and Cancel buttons can be fired with the ENTER and ESC key, respectively.

=== Contents Definition ===

The "contents" property is the most important in the definition. It defines the actual dialog contents. Note that this property is an array. Each entry in this array is an object. Each object will be represented by a "tab" in the dialog. No tabs are shown if just one object is defined.

The following is the compact representation of a single contents object:
<pre>{
id: 'unique name',
label: 'Tab Label',
title: 'Contents description',
accessKey: 'Q',
elements : [ ... ]
}
</pre>
Just like the buttons, here again we have id, label, title and access key to be defined for each content object. It is possible to activate one of the tabs by using the CTRL + access key. It is also possible to switching between the tabs by hitting CTRL+SPACE (forward) and CTRL+SHIFT+SPACE (backward).

The "elements" array contains the UI element definitions for this contents object. Details can be found in the next section.

== UI Elements ==

The inner part of the dialog is finally filled with "UI elements". For example, the following is a possible definition for a simple text field:
<pre>{
id: 'width',
type: 'text',
label: editor.lang.width,
title: editor.lang.widthTitle,
default: '120',
className: 'anyClass',
style: 'someStyles',
onLoad: function( data ) { ... }
}
</pre>
Most of the properties are optional, including "id" property, but it is recommended as it makes it easier to customize the dialog.

The "type" property is required. It indicates which "UI element builder" to use for this element. The dialog core code provides only two element types, "vbox" and "hbox", which are containers for other elements:
<pre>{
type: 'vbox|hbox',
children: [ ... ]
}
</pre>
The "vbox" element will dispose all children elements vertically, one bellow the other. The "hbox" element will place then one next to the other horizontally instead.

The main contents placeholder itself is rendered by a vbox element object.

=== Defining Elements ===

Plugins or inline code can easily define new dialog UI elements to be used inside the dialogs. For that, "UI element builders" must be registered with the following call:
<pre>CKEDITOR.dialog.addUIElement( 'type name',
{
build : function( elementDefinition, output )
{
// render the element to the output (Array)

return {
setValue : function( value, resetChanged )
{
// set the element value, based on the elementBag
// information.
},

getValue : function()
{
// returns the current value.
},

isChanged : function()
{
// returns a Boolean indicating that the value
// has been changed.
},

focus : function()
{
}
};
}
});
</pre>
The elementDefinition parameter is the exact element object taken from the dialog definition. If the element handles children elements, it is also responsible for calling the build function for those elements.

The build function returns an object, which will be used to handle this element at runtime.

=== Elements Plugin ===

The editor comes with the "dialogui" plugin, which defines the most common dialog UI elements types:
<pre>{
type : 'text',
label : 'Label Text',
title : 'Field description',
default : '...',
className: '...',
style: '...',
required: true/false,
validate: function() { ... }
}

{
type : 'select',
label : 'Label Text',
title : 'Field description',
default : '...',
className: '...',
style: '...',
required: true/false,
validate: function() { ... }
items:
[
[ 'Label 1', 'Value' ],
[ 'Label 2' ] // Value is 'Label 2'
]
}

{
type : 'radio',
label : 'Label Text',
title : 'Field description',
default : '...',
className: '...',
style: '...',
required: true/false,
validate: function() { ... },
items:
[
[ 'Label 1', 'Value', 'Title' ],
[ 'Label 2' ] // Value and Title are 'Label 2'
]
}

{
type : 'checkbox',
label : 'Label Text',
title : 'Field description',
checked : true|false,
className: '...',
style: '...',
required: true/false,
validate: function() { ... }
}

{
type : 'button',
label : 'Label Text',
title : 'Field description',
className: '...',
style: '...',
onClick : function(){ ... }
}

{
type : 'html',
className: '...',
style: '...',
html: 'Some <b>HTML</b>'
}

</pre>
== Workflow ==

When loading the dialog:

*editor.openDialog( 'dialogName' ) is called.
*The dialog system shows the cover (hourglass icon).
*The dialog definition for 'dialogName' is loaded.
*If needed, the dialog definition is downloaded.
*editor.theme.buildDialog() is called returning the main structure HTML
*The main structure HTML is injected into the DOM (hidden).
*Based on the dialog definition, the dialog system fills the dialog title, enables the resize handler and creates the dialog buttons.
*The "onLoad" function is called for the dialog definition.
*Tabs are created for the content objects.
*The "onLoad" is called for each UI elements defined (recursively on children elements also).
*All elements in the content object to be displayed are rendered.
*The resulting rendered HTML is injected into the DOM.
*The dialog is displayed (normal icon).

When hitting Ok:

*The "validate" function is called for each element. If any of them is invalid, the focus is moved to it, and a standard UI alert is displayed.
*The "onOk" function is called.
*If "onOk" doesn't return "false", the dialog gets destroyed.

When hitting Cancel:

*The "isChanged" function is called for each element. If any of then has been changed, a standard warning message is displayed ("Are you sure blah blah...?").
*The "onCancel" function is called.
*If "onCancel" doesn't return "false", the dialog gets destroyed.

== Dialog Definition API Extensions ==

Once registered, a dialog definition gets "extended" by the dialog system. A few API functions are added to it, making it possible to manipulate it:

*getContents( 'id' ): gets a specific contents object, by id.
*getButton( 'id' ): gets a specific button object, by id.
*addContents( { ... contents object } [, nextSiblingId] ): adds a content object to the definitions. If the second parameter is specify, the added object is placed before the object with that id, otherwise it is appended to the end.
*addButton( { ... button object } [,nextSiblingId] ): the same exact behavior of addContents, but for the buttons.
*removeContents( 'id' ): removes one of the contents objects.
*removeButton( 'id' ): removes one of the buttons.

Contents objects are extended with the following functions:

*get( 'id' ): gets one of the UI elements by id.
*add( { ... element definition } [,nextSiblingId] ): just like addContents, it adds UI elements to the list.
*remove( 'id' ): removes one of the UI elements.

Button object are extended with the following functions:

*enable(): enables the button.
*disable(): disables the button.

CKFinder 1.x/Developers Guide/ASP/Configuration/Quick Start

2010-03-17T09:34:39Z

Fredck: Fixed typo.

== The CheckAuthentication function<br> ==

By default, CKFinder will not work due to authentication restrictions. You must first be sure that you have configured it properly, and then enable it.

Once you have completely configured CKFinder, you are ready to enable it for use. The CheckAuthentication() function is used for that. In this function, you must implement the code that ensures that the requests are coming from an authenticated user. This is usually done by assigning a session variable when the user logs on your system.

Return "true" if the user is properly authenticated. We strongly recommend you to NOT simply return "true" from this function without implementing authentication checks. Anonymous users would be able to use CKFinder, including uploading and deleting files from your server.

The following is a sample implementation for it:
<pre>function CheckAuthentication()
CheckAuthentication = ( Session( "IsAuthorized" ) )
End function
</pre>

=== License ===

If you purchased CKFinder you should put your license key in the config.php file:
<pre>CKFinder_Config.Add "LicenseName", ""
CKFinder_Config.Add "LicenseKey", ""</pre>
If you leave this fields blank CKFinder will be fully functional but it will be running in demo mode.

=== baseUrl ===

The '''baseUrl''' is the base path used to build the final URL for the resources handled in CKFinder. Examples:
<pre>baseUrl = "http://example.com/ckfinder/files/"
baseUrl = "/userfiles/"</pre>
If you leave this field empty the default value (/userfiles/) will be used. Notice that the trailing slash is required.

=== baseDir ===

The '''baseDir''' is the path to the local directory (in the server) which points to the above baseUrl URL. This is the path used by CKFinder to handle the files in the server. Full write permissions must be granted to this directory. Examples:

You may point it to a directory directly:
<pre>baseDir = "/home/login/public_html/ckfinder/files/"
baseDir = "C:\SiteDir\CKFinder\userfiles\"</pre>
Or you may let CKFinder discover the path, based on baseUrl:
<pre>baseDir = server.MapPath(baseUrl) & "\"</pre>
Remember that CKFinder will only discover the path when the base url is a local web path ( relative to document root ).<br>Example:
<pre>baseUrl = "/userfiles/"</pre>
If it is a full URL address.<br>Example:
<pre>baseUrl = "http://example.com/ckfinder/files/"</pre>
the path won't be discovered. Notice that the trailing slash is required.

FCKeditor 3.x/Design and Architecture/ARIA Described

2010-02-19T12:15:03Z

Fredck: /* Dialogs */ Updated recent changes to the tabs structure

This page provides technical information about the ARIA support provided in CKEditor (starting at version 3.2.).

CKEditor 3.2 is fully "ARIA aware". In fact all the accessibility support preset in the editor core has been switched to ARIA, without considering specific accessibility requirements and limitations existing on browsers and assistive technology (mostly).

Currently Firefox 3.5+ and JAWS 11 provide the best accessibility experience with CKEditor. These tools are our recommendation when accessibility is needed. IE8 is also a good option, but not as good as Firefox 3.5.

== The "application" root ==

Each of the editor instances is enclosed into the following element, placed in the exact DOM location we expect the editor to be shown:

<pre>
<span id="cke_[editor-name]" role="application" aria-labelledby="cke_[editor-name]_arialbl" ...>
<span id="cke_[editor-name]_arialbl">Rich Text Editor</span>
....
[ Here goes the editor ]
....
</span>
</pre>

This created a landmark in the page for each editor, and ATs should enter in application mode when reaching it.

== The inner structure ==

Inside the application root, we have a complex structure that defines the editor interface. We have a couple of <nowiki><span></nowiki> elements holding a <nowiki><table></nowiki> element which defines the main editor spaces: top, contents and bottom. This complex structure is necessary to workaround CSS limitations present in some browsers (IE6/IE Quirks).

Here is a simplification of it:

<pre>
<span ...>
<span ...>
<table ...>
<tr><td class="cke_top" ...>
[ Top elements ]
</td></tr>
<tr><td class="cke_contents" ...>
[ Contents elements ]
</td></tr>
<tr><td class="cke_bottom" ...>
[ Bottom elements ]
</td></tr>
</table>
</span>
</span>
</pre>

All elements in this structure are marked with the "presentation" role. In this way they are ignored in the accessibility description of the page.

== The Toolbar ==

The editor toolbar is rendered, by default, into the top space of the inner editor structure. Internally, it's called instead "toolbox", which holds a series of small "toolbars".

The following represents its structure:

<pre>
<div role="toolbar" class="cke_toolbox" aria-labelledby="cke_[number]">
<span id="cke_[number]">Toolbar</span>
...
[ "n" toolbars]
...
</div>
</pre>

Inside the above toolbox we'll have then several "toolbars", each of them having the following structure:

<pre>
<span class="cke_toolbar" role="presentation">
...
[ "n" toolbar groups ]
...
</span>
</pre>

Each toolbar will then contain a series of "toolbar groups", with the following structure:

<pre>
<span class="cke_toolgroup" role="presentation">
...
[ "n" toolbar items ]
...
</span>
</pre>

This complex structure makes the UI quite flexible, so rich skinning is possible.

Finally, the toolbar groups hold the toolbar items. Currently, the following types of items are available: Button, Menu Button and Combo Box.

When moving the UI focus into the toolbar (ALT+F10), it's first element is focused.

=== Toolbar Button ===

The following is the structure of a toolbar Button (e.g. the Source button):

<pre>
<span class="cke_button">
<a role="button" aria-labelledby="cke_5_label" tabindex="-1" title="Source">
<span class="cke_icon"></span>
<span class="cke_label" id="cke_5_label">Source</span>
</a>
</span>
</pre>

=== Toolbar Menu Button ===

The following is the structure of a toolbar Menu Button (e.g. the Text Color button):

<pre>
<span class="cke_button">
<a role="button" aria-haspopup="true" aria-labelledby="cke_75_label" tabindex="-1" title="Text Color">
<span class="cke_icon"></span>
<span class="cke_label" id="cke_75_label">Text Color</span>
<span class="cke_buttonarrow"></span>
</a>
</span>
</pre>

=== Toolbar Combo Box ===

The following is the structure of a toolbar Combo Box (e.g. the Font Size combo box):

<pre>
<span class="cke_rcombo">
<span class="cke_fontSize cke_off" id="cke_73">
<span class="cke_label" id="cke_73_label">Size</span>
<a role="button" aria-haspopup="true" aria-labelledby="cke_73_label" aria-describedby="cke_73_text" tabindex="-1" title="Font Size">
<span>
<span id="cke_73_text">[ Current Value ]</span>
</span>
<span class="cke_openbutton"></span>
</a>
</span>
</span>
</pre>

For the visually impaired, what we graphically represent and call as combos will act just like Menu Buttons. This is done because the user must activate it by pressing space bar, instead of changing their values directly with the arrow keys. This brings no usability impact to the visually impaired.

When activating (opening) a combo, a floating panel is created on the fly, holding the list of items available for that combo. The following structure represents it:

<pre>
<div role="presentation">
<div role="presentation">
<iframe role="listbox" aria-label="Font Size">

<html>
<head></head>
<body>
<div tabindex="-1" role="presentation">
<h1 role="presentation">Font Size</h1>
<ul role="presentation">

<li>
<a role="option" aria-posinset="1" title="8" aria-setsize="16">
<span>8</span>
</a>
</li>
...
[ Repetitions of the above <li> structure for each item in the list ]
...
</ul>
</div>
</body>
</html>

</iframe>
</div>
</div>
</pre>

After opened, the UI focus is set to the "listbox" <iframe>. Then, when using the ARROW-DOWN key, the first list item is focused.

== The Elements Path ==

The Elements Path is rendered at the bottom space of the inner structure of the editor. The following represents its structure scheme:

<pre>
<span id="cke_path_editor1_label">Elements path</span>
<div role="group" aria-labelledby="cke_path_editor1_label">
<a role="button" aria-labelledby="cke_elementspath_2_2_label" title="body element" tabindex="-1">
body
<span id="cke_elementspath_2_2_label">body element</span>
</a>
...
[ Several of the above <a> structures for each element ]
...
</div>
</pre>

When moving the UI focus into the elements path (ALT+F11), the button representing it's deeper element is focused.

== The Editing Area ==

The editing area is rendered into the contents space of the inner editor structure. By default the editor provides two editing modes: WYSIWYG and Source.

=== WYSIWYG Mode ===

In WYSIWYG mode, the editor renders an <iframe> element, setting its contents as editable through the contenteditable attribute in the <body> element (for IE only) or the document.designMode DOM property (all other browsers).

The following represents this structure, including the inner document:

<pre>
<iframe tabindex="0">
<html>
<head>
<title>Rich text editor, editor1, press ALT 0 for help.</title>
</head>
<body>
...
[ The raw HTML contents of the editor ]
...
</body>
</html>
</iframe>
</pre>

Note that no ARIA attributes are used here. ATs should use the default role for HTML documents, which is "document", enhanced by the enabled editing support.

=== Source Mode ===

In Source mode, the editor simply renders a <textarea> element. The following represents its definition:

<pre>
<textarea tabindex="0" role="textbox" aria-label="Rich text editor, editor1, press ALT 0 for help.">
...
[ The raw HTML contents of the editor ]
...
</textarea>
</pre>

=== Focus grabbing ===

The application root doesn't wait for user focus directly (tabindex=-1). It instead expects having elements inside of it that would participate in the page tabbing order.

In a standard editor installation, the editing area is the only element that participates into the page tabbing. The tabindex used for it is inherited from the <textarea> replaced by the editor, or even specified through the "tabIndex" setting.

In the WYSIWYG mode, the element that receives the focus is the <iframe> element that holds the editable document. In Source mode, we have instead a normal <textarea> element.

None of the other UI elements in the editor, like the toolbar or the elements path, will participate in the page tabbing order. Focus and tabbing in these elements is managed by the editor code.

== Dialogs ==

Some of the editor commands open UI dialogs. Those are floating elements usually used to request user information for the creation and modification of specific elements, like links and tables.

The following is a sample for the full structure of a dialog, including it's basic UI elements (the Anchor dialog is used to exemplify):

<pre>
<div role="dialog" aria-labelledby="cke_dialog_title_91">
<table role="presentation">
<tr><td role="presentation">
<div role="presentation" class="cke_dialog_body">


<div role="presentation" class="cke_dialog_title" id="cke_dialog_title_91">Anchor Properties</div>


<a role="button" title="Close"><span class="cke_label">X</span></a>


<div role="tablist">
<a role="tab" aria-labelledby="info_98_arialbl" tabindex="-1" title="Anchor Properties">
<span id="info_98_arialbl">Anchor Properties</span>
</a>
...
[ Repetitions of the above <a> for each tab ]
...
</div>


<table role="presentation">
<tr><td role="presentation">
<div role="tabpanel" aria-hidden="false">
...
[ Dialog contents ]
...
</div>
</td></tr>
</table>


<div role="presentation" class="cke_dialog_footer">
<table role="presentation">
<tr><td role="presentation">
<a role="button" aria-labelledby="100_label" title="OK">
<span id="100_label">OK</span>
</a>
</td>
...
[ The same <td> structure for the "Cancel" button ]
...
</tr>
</table>
</div>
</div>
...
</td></tr>
</table>
</div>
</pre>

As soon as the dialog is rendered, the UI focus is set into one of its content elements (usually an <input> element).

Tabbing inside dialogs is managed by the editor code.

== Context Menu ==

The context menu is a floating element created on the fly at first open. This element holds an <iframe> element into which the menu contents is rendered.

The following represents its structure:

<pre>
<div role="presentation">
<div role="presentation">
<iframe role="menu" aria-label="Options">

<html>
<head></head>
<body>
<div tabindex="-1" role="presentation">
<div role="presentation" class="cke_menu">

<span class="cke_menuitem">
<a role="menuitem" tabindex="-1" title="Cut">
<span class="cke_icon_wrapper"><span></span></span>
<span class="cke_label">Cut</span>
</a>
</span>
...
[ Repetitions of the above <span> structure of each menu item ]
...
</div>
</div>
</body>
</html>

</iframe>
</div>
</div>
</pre>

When opened, the UI focus is set to the "menu" <iframe>. Then, when using the ARROW-DOWN key, the first menu item is focused.

== Notes ==

* Floating elements, like dialogs, context menus or combos and menu buttons panels, are not created inside the application root element. They are instead placed at the very end of the page structure, right before the </body> element closing. It's done in this way because a single panel can be used by more than one editor instance present in the page (to enhance performance and save resources).

* We avoid using "aria-label", using instead "aria-labelledby". In an ARIA point of view, this is not necessary in most cases, and it even makes the DOM structure and our code more complex, but unfortunately IE has no support for "aria-label".

* The aria-disabled attribute is properly used to indicate buttons and menu options that are disabled.

* We use the <a> element for several UI elements (like buttons, menu items, tabs, etc). In this way we are able to use the :hover CSS pseudo-class, which is not supported in all elements in some browsers.

* The HTML structures illustrated in this page are not complete, including exclusively the elements and attributes that have ARIA relevance or that enhances the structure understanding.

FCKeditor 3.x/Design and Architecture/ARIA Described

2010-02-17T13:14:29Z

Fredck: /* The inner structure */

This page provides technical information about the ARIA support provided in CKEditor (starting at version 3.2.).

CKEditor 3.2 is fully "ARIA aware". In fact all the accessibility support preset in the editor core has been switched to ARIA, without considering specific accessibility requirements and limitations existing on browsers and assistive technology (mostly).

Currently Firefox 3.5+ and JAWS 11 provide the best accessibility experience with CKEditor. These tools are our recommendation when accessibility is needed. IE8 is also a good option, but not as good as Firefox 3.5.

== The "application" root ==

Each of the editor instances is enclosed into the following element, placed in the exact DOM location we expect the editor to be shown:

<pre>
<span id="cke_[editor-name]" role="application" aria-labelledby="cke_[editor-name]_arialbl" ...>
<span id="cke_[editor-name]_arialbl">Rich Text Editor</span>
....
[ Here goes the editor ]
....
</span>
</pre>

This created a landmark in the page for each editor, and ATs should enter in application mode when reaching it.

== The inner structure ==

Inside the application root, we have a complex structure that defines the editor interface. We have a couple of <nowiki><span></nowiki> elements holding a <nowiki><table></nowiki> element which defines the main editor spaces: top, contents and bottom. This complex structure is necessary to workaround CSS limitations present in some browsers (IE6/IE Quirks).

Here is a simplification of it:

<pre>
<span ...>
<span ...>
<table ...>
<tr><td class="cke_top" ...>
[ Top elements ]
</td></tr>
<tr><td class="cke_contents" ...>
[ Contents elements ]
</td></tr>
<tr><td class="cke_bottom" ...>
[ Bottom elements ]
</td></tr>
</table>
</span>
</span>
</pre>

All elements in this structure are marked with the "presentation" role. In this way they are ignored in the accessibility description of the page.

== The Toolbar ==

The editor toolbar is rendered, by default, into the top space of the inner editor structure. Internally, it's called instead "toolbox", which holds a series of small "toolbars".

The following represents its structure:

<pre>
<div role="toolbar" class="cke_toolbox" aria-labelledby="cke_[number]">
<span id="cke_[number]">Toolbar</span>
...
[ "n" toolbars]
...
</div>
</pre>

Inside the above toolbox we'll have then several "toolbars", each of them having the following structure:

<pre>
<span class="cke_toolbar" role="presentation">
...
[ "n" toolbar groups ]
...
</span>
</pre>

Each toolbar will then contain a series of "toolbar groups", with the following structure:

<pre>
<span class="cke_toolgroup" role="presentation">
...
[ "n" toolbar items ]
...
</span>
</pre>

This complex structure makes the UI quite flexible, so rich skinning is possible.

Finally, the toolbar groups hold the toolbar items. Currently, the following types of items are available: Button, Menu Button and Combo Box.

When moving the UI focus into the toolbar (ALT+F10), it's first element is focused.

=== Toolbar Button ===

The following is the structure of a toolbar Button (e.g. the Source button):

<pre>
<span class="cke_button">
<a role="button" aria-labelledby="cke_5_label" tabindex="-1" title="Source">
<span class="cke_icon"></span>
<span class="cke_label" id="cke_5_label">Source</span>
</a>
</span>
</pre>

=== Toolbar Menu Button ===

The following is the structure of a toolbar Menu Button (e.g. the Text Color button):

<pre>
<span class="cke_button">
<a role="button" aria-haspopup="true" aria-labelledby="cke_75_label" tabindex="-1" title="Text Color">
<span class="cke_icon"></span>
<span class="cke_label" id="cke_75_label">Text Color</span>
<span class="cke_buttonarrow"></span>
</a>
</span>
</pre>

=== Toolbar Combo Box ===

The following is the structure of a toolbar Combo Box (e.g. the Font Size combo box):

<pre>
<span class="cke_rcombo">
<span class="cke_fontSize cke_off" id="cke_73">
<span class="cke_label" id="cke_73_label">Size</span>
<a role="button" aria-haspopup="true" aria-labelledby="cke_73_label" aria-describedby="cke_73_text" tabindex="-1" title="Font Size">
<span>
<span id="cke_73_text">[ Current Value ]</span>
</span>
<span class="cke_openbutton"></span>
</a>
</span>
</span>
</pre>

For the visually impaired, what we graphically represent and call as combos will act just like Menu Buttons. This is done because the user must activate it by pressing space bar, instead of changing their values directly with the arrow keys. This brings no usability impact to the visually impaired.

When activating (opening) a combo, a floating panel is created on the fly, holding the list of items available for that combo. The following structure represents it:

<pre>
<div role="presentation">
<div role="presentation">
<iframe role="listbox" aria-label="Font Size">

<html>
<head></head>
<body>
<div tabindex="-1" role="presentation">
<h1 role="presentation">Font Size</h1>
<ul role="presentation">

<li>
<a role="option" aria-posinset="1" title="8" aria-setsize="16">
<span>8</span>
</a>
</li>
...
[ Repetitions of the above <li> structure for each item in the list ]
...
</ul>
</div>
</body>
</html>

</iframe>
</div>
</div>
</pre>

After opened, the UI focus is set to the "listbox" <iframe>. Then, when using the ARROW-DOWN key, the first list item is focused.

== The Elements Path ==

The Elements Path is rendered at the bottom space of the inner structure of the editor. The following represents its structure scheme:

<pre>
<span id="cke_path_editor1_label">Elements path</span>
<div role="group" aria-labelledby="cke_path_editor1_label">
<a role="button" aria-labelledby="cke_elementspath_2_2_label" title="body element" tabindex="-1">
body
<span id="cke_elementspath_2_2_label">body element</span>
</a>
...
[ Several of the above <a> structures for each element ]
...
</div>
</pre>

When moving the UI focus into the elements path (ALT+F11), the button representing it's deeper element is focused.

== The Editing Area ==

The editing area is rendered into the contents space of the inner editor structure. By default the editor provides two editing modes: WYSIWYG and Source.

=== WYSIWYG Mode ===

In WYSIWYG mode, the editor renders an <iframe> element, setting its contents as editable through the contenteditable attribute in the <body> element (for IE only) or the document.designMode DOM property (all other browsers).

The following represents this structure, including the inner document:

<pre>
<iframe tabindex="0">
<html>
<head>
<title>Rich text editor, editor1, press ALT 0 for help.</title>
</head>
<body>
...
[ The raw HTML contents of the editor ]
...
</body>
</html>
</iframe>
</pre>

Note that no ARIA attributes are used here. ATs should use the default role for HTML documents, which is "document", enhanced by the enabled editing support.

=== Source Mode ===

In Source mode, the editor simply renders a <textarea> element. The following represents its definition:

<pre>
<textarea tabindex="0" role="textbox" aria-label="Rich text editor, editor1, press ALT 0 for help.">
...
[ The raw HTML contents of the editor ]
...
</textarea>
</pre>

=== Focus grabbing ===

The application root doesn't wait for user focus directly (tabindex=-1). It instead expects having elements inside of it that would participate in the page tabbing order.

In a standard editor installation, the editing area is the only element that participates into the page tabbing. The tabindex used for it is inherited from the <textarea> replaced by the editor, or even specified through the "tabIndex" setting.

In the WYSIWYG mode, the element that receives the focus is the <iframe> element that holds the editable document. In Source mode, we have instead a normal <textarea> element.

None of the other UI elements in the editor, like the toolbar or the elements path, will participate in the page tabbing order. Focus and tabbing in these elements is managed by the editor code.

== Dialogs ==

Some of the editor commands open UI dialogs. Those are floating elements usually used to request user information for the creation and modification of specific elements, like links and tables.

The following is a sample for the full structure of a dialog, including it's basic UI elements (the Anchor dialog is used to exemplify):

<pre>
<div role="dialog" aria-labelledby="cke_dialog_title_91">
<table role="presentation">
<tr><td role="presentation">
<div role="presentation" class="cke_dialog_body">


<div role="presentation" class="cke_dialog_title" id="cke_dialog_title_91">Anchor Properties</div>


<a role="button" title="Close"><span class="cke_label">X</span></a>


<div role="tablist" aria-labelledby="cke_dialog_tabs_91_arialbl">
<span id="cke_dialog_tabs_91_arialbl">Dialog Tabs</span>
<a role="tab" aria-labelledby="info_98_arialbl" tabindex="-1" title="Anchor Properties">
<span id="info_98_arialbl">Anchor Properties</span>
</a>
...
[ Repetitions of the above <a> for each tab ]
...
</div>


<table role="presentation">
<tr><td role="presentation">
<div role="tabpanel" aria-hidden="false">
...
[ Dialog contents ]
...
</div>
</td></tr>
</table>


<div role="presentation" class="cke_dialog_footer">
<table role="presentation">
<tr><td role="presentation">
<a role="button" aria-labelledby="100_label" title="OK">
<span id="100_label">OK</span>
</a>
</td>
...
[ The same <td> structure for the "Cancel" button ]
...
</tr>
</table>
</div>
</div>
...
</td></tr>
</table>
</div>
</pre>

As soon as the dialog is rendered, the UI focus is set into one of its content elements (usually an <input> element).

Tabbing inside dialogs is managed by the editor code.

== Context Menu ==

The context menu is a floating element created on the fly at first open. This element holds an <iframe> element into which the menu contents is rendered.

The following represents its structure:

<pre>
<div role="presentation">
<div role="presentation">
<iframe role="menu" aria-label="Options">

<html>
<head></head>
<body>
<div tabindex="-1" role="presentation">
<div role="presentation" class="cke_menu">

<span class="cke_menuitem">
<a role="menuitem" tabindex="-1" title="Cut">
<span class="cke_icon_wrapper"><span></span></span>
<span class="cke_label">Cut</span>
</a>
</span>
...
[ Repetitions of the above <span> structure of each menu item ]
...
</div>
</div>
</body>
</html>

</iframe>
</div>
</div>
</pre>

When opened, the UI focus is set to the "menu" <iframe>. Then, when using the ARROW-DOWN key, the first menu item is focused.

== Notes ==

* Floating elements, like dialogs, context menus or combos and menu buttons panels, are not created inside the application root element. They are instead placed at the very end of the page structure, right before the </body> element closing. It's done in this way because a single panel can be used by more than one editor instance present in the page (to enhance performance and save resources).

* We avoid using "aria-label", using instead "aria-labelledby". In an ARIA point of view, this is not necessary in most cases, and it even makes the DOM structure and our code more complex, but unfortunately IE has no support for "aria-label".

* The aria-disabled attribute is properly used to indicate buttons and menu options that are disabled.

* We use the <a> element for several UI elements (like buttons, menu items, tabs, etc). In this way we are able to use the :hover CSS pseudo-class, which is not supported in all elements in some browsers.

* The HTML structures illustrated in this page are not complete, including exclusively the elements and attributes that have ARIA relevance or that enhances the structure understanding.

FCKeditor 3.x/Design and Architecture/ARIA Described

2010-02-17T13:12:18Z

Fredck: Created page with 'This page provides technical information about the ARIA support provided in CKEditor (starting at version 3.2.). CKEditor 3.2 is fully "ARIA aware". In fact all the accessibilit…'

This page provides technical information about the ARIA support provided in CKEditor (starting at version 3.2.).

CKEditor 3.2 is fully "ARIA aware". In fact all the accessibility support preset in the editor core has been switched to ARIA, without considering specific accessibility requirements and limitations existing on browsers and assistive technology (mostly).

Currently Firefox 3.5+ and JAWS 11 provide the best accessibility experience with CKEditor. These tools are our recommendation when accessibility is needed. IE8 is also a good option, but not as good as Firefox 3.5.

== The "application" root ==

Each of the editor instances is enclosed into the following element, placed in the exact DOM location we expect the editor to be shown:

<pre>
<span id="cke_[editor-name]" role="application" aria-labelledby="cke_[editor-name]_arialbl" ...>
<span id="cke_[editor-name]_arialbl">Rich Text Editor</span>
....
[ Here goes the editor ]
....
</span>
</pre>

This created a landmark in the page for each editor, and ATs should enter in application mode when reaching it.

== The inner structure ==

Inside the application root, we have a complex structure that defines the editor interface. We have a couple of <span> elements holding a <table> element which defines the main editor spaces: top, contents and bottom. This complex structure is necessary to workaround CSS limitations present in some browsers (IE6/IE Quirks).

Here is a simplification of it:

<pre>
<span ...>
<span ...>
<table ...>
<tr><td class="cke_top" ...>
[ Top elements ]
</td></tr>
<tr><td class="cke_contents" ...>
[ Contents elements ]
</td></tr>
<tr><td class="cke_bottom" ...>
[ Bottom elements ]
</td></tr>
</table>
</span>
</span>
</pre>

All elements in this structure are marked with the "presentation" role. In this way they are ignored in the accessibility description of the page.

== The Toolbar ==

The editor toolbar is rendered, by default, into the top space of the inner editor structure. Internally, it's called instead "toolbox", which holds a series of small "toolbars".

The following represents its structure:

<pre>
<div role="toolbar" class="cke_toolbox" aria-labelledby="cke_[number]">
<span id="cke_[number]">Toolbar</span>
...
[ "n" toolbars]
...
</div>
</pre>

Inside the above toolbox we'll have then several "toolbars", each of them having the following structure:

<pre>
<span class="cke_toolbar" role="presentation">
...
[ "n" toolbar groups ]
...
</span>
</pre>

Each toolbar will then contain a series of "toolbar groups", with the following structure:

<pre>
<span class="cke_toolgroup" role="presentation">
...
[ "n" toolbar items ]
...
</span>
</pre>

This complex structure makes the UI quite flexible, so rich skinning is possible.

Finally, the toolbar groups hold the toolbar items. Currently, the following types of items are available: Button, Menu Button and Combo Box.

When moving the UI focus into the toolbar (ALT+F10), it's first element is focused.

=== Toolbar Button ===

The following is the structure of a toolbar Button (e.g. the Source button):

<pre>
<span class="cke_button">
<a role="button" aria-labelledby="cke_5_label" tabindex="-1" title="Source">
<span class="cke_icon"></span>
<span class="cke_label" id="cke_5_label">Source</span>
</a>
</span>
</pre>

=== Toolbar Menu Button ===

The following is the structure of a toolbar Menu Button (e.g. the Text Color button):

<pre>
<span class="cke_button">
<a role="button" aria-haspopup="true" aria-labelledby="cke_75_label" tabindex="-1" title="Text Color">
<span class="cke_icon"></span>
<span class="cke_label" id="cke_75_label">Text Color</span>
<span class="cke_buttonarrow"></span>
</a>
</span>
</pre>

=== Toolbar Combo Box ===

The following is the structure of a toolbar Combo Box (e.g. the Font Size combo box):

<pre>
<span class="cke_rcombo">
<span class="cke_fontSize cke_off" id="cke_73">
<span class="cke_label" id="cke_73_label">Size</span>
<a role="button" aria-haspopup="true" aria-labelledby="cke_73_label" aria-describedby="cke_73_text" tabindex="-1" title="Font Size">
<span>
<span id="cke_73_text">[ Current Value ]</span>
</span>
<span class="cke_openbutton"></span>
</a>
</span>
</span>
</pre>

For the visually impaired, what we graphically represent and call as combos will act just like Menu Buttons. This is done because the user must activate it by pressing space bar, instead of changing their values directly with the arrow keys. This brings no usability impact to the visually impaired.

When activating (opening) a combo, a floating panel is created on the fly, holding the list of items available for that combo. The following structure represents it:

<pre>
<div role="presentation">
<div role="presentation">
<iframe role="listbox" aria-label="Font Size">

<html>
<head></head>
<body>
<div tabindex="-1" role="presentation">
<h1 role="presentation">Font Size</h1>
<ul role="presentation">

<li>
<a role="option" aria-posinset="1" title="8" aria-setsize="16">
<span>8</span>
</a>
</li>
...
[ Repetitions of the above <li> structure for each item in the list ]
...
</ul>
</div>
</body>
</html>

</iframe>
</div>
</div>
</pre>

After opened, the UI focus is set to the "listbox" <iframe>. Then, when using the ARROW-DOWN key, the first list item is focused.

== The Elements Path ==

The Elements Path is rendered at the bottom space of the inner structure of the editor. The following represents its structure scheme:

<pre>
<span id="cke_path_editor1_label">Elements path</span>
<div role="group" aria-labelledby="cke_path_editor1_label">
<a role="button" aria-labelledby="cke_elementspath_2_2_label" title="body element" tabindex="-1">
body
<span id="cke_elementspath_2_2_label">body element</span>
</a>
...
[ Several of the above <a> structures for each element ]
...
</div>
</pre>

When moving the UI focus into the elements path (ALT+F11), the button representing it's deeper element is focused.

== The Editing Area ==

The editing area is rendered into the contents space of the inner editor structure. By default the editor provides two editing modes: WYSIWYG and Source.

=== WYSIWYG Mode ===

In WYSIWYG mode, the editor renders an <iframe> element, setting its contents as editable through the contenteditable attribute in the <body> element (for IE only) or the document.designMode DOM property (all other browsers).

The following represents this structure, including the inner document:

<pre>
<iframe tabindex="0">
<html>
<head>
<title>Rich text editor, editor1, press ALT 0 for help.</title>
</head>
<body>
...
[ The raw HTML contents of the editor ]
...
</body>
</html>
</iframe>
</pre>

Note that no ARIA attributes are used here. ATs should use the default role for HTML documents, which is "document", enhanced by the enabled editing support.

=== Source Mode ===

In Source mode, the editor simply renders a <textarea> element. The following represents its definition:

<pre>
<textarea tabindex="0" role="textbox" aria-label="Rich text editor, editor1, press ALT 0 for help.">
...
[ The raw HTML contents of the editor ]
...
</textarea>
</pre>

=== Focus grabbing ===

The application root doesn't wait for user focus directly (tabindex=-1). It instead expects having elements inside of it that would participate in the page tabbing order.

In a standard editor installation, the editing area is the only element that participates into the page tabbing. The tabindex used for it is inherited from the <textarea> replaced by the editor, or even specified through the "tabIndex" setting.

In the WYSIWYG mode, the element that receives the focus is the <iframe> element that holds the editable document. In Source mode, we have instead a normal <textarea> element.

None of the other UI elements in the editor, like the toolbar or the elements path, will participate in the page tabbing order. Focus and tabbing in these elements is managed by the editor code.

== Dialogs ==

Some of the editor commands open UI dialogs. Those are floating elements usually used to request user information for the creation and modification of specific elements, like links and tables.

The following is a sample for the full structure of a dialog, including it's basic UI elements (the Anchor dialog is used to exemplify):

<pre>
<div role="dialog" aria-labelledby="cke_dialog_title_91">
<table role="presentation">
<tr><td role="presentation">
<div role="presentation" class="cke_dialog_body">


<div role="presentation" class="cke_dialog_title" id="cke_dialog_title_91">Anchor Properties</div>


<a role="button" title="Close"><span class="cke_label">X</span></a>


<div role="tablist" aria-labelledby="cke_dialog_tabs_91_arialbl">
<span id="cke_dialog_tabs_91_arialbl">Dialog Tabs</span>
<a role="tab" aria-labelledby="info_98_arialbl" tabindex="-1" title="Anchor Properties">
<span id="info_98_arialbl">Anchor Properties</span>
</a>
...
[ Repetitions of the above <a> for each tab ]
...
</div>


<table role="presentation">
<tr><td role="presentation">
<div role="tabpanel" aria-hidden="false">
...
[ Dialog contents ]
...
</div>
</td></tr>
</table>


<div role="presentation" class="cke_dialog_footer">
<table role="presentation">
<tr><td role="presentation">
<a role="button" aria-labelledby="100_label" title="OK">
<span id="100_label">OK</span>
</a>
</td>
...
[ The same <td> structure for the "Cancel" button ]
...
</tr>
</table>
</div>
</div>
...
</td></tr>
</table>
</div>
</pre>

As soon as the dialog is rendered, the UI focus is set into one of its content elements (usually an <input> element).

Tabbing inside dialogs is managed by the editor code.

== Context Menu ==

The context menu is a floating element created on the fly at first open. This element holds an <iframe> element into which the menu contents is rendered.

The following represents its structure:

<pre>
<div role="presentation">
<div role="presentation">
<iframe role="menu" aria-label="Options">

<html>
<head></head>
<body>
<div tabindex="-1" role="presentation">
<div role="presentation" class="cke_menu">

<span class="cke_menuitem">
<a role="menuitem" tabindex="-1" title="Cut">
<span class="cke_icon_wrapper"><span></span></span>
<span class="cke_label">Cut</span>
</a>
</span>
...
[ Repetitions of the above <span> structure of each menu item ]
...
</div>
</div>
</body>
</html>

</iframe>
</div>
</div>
</pre>

When opened, the UI focus is set to the "menu" <iframe>. Then, when using the ARROW-DOWN key, the first menu item is focused.

== Notes ==

* Floating elements, like dialogs, context menus or combos and menu buttons panels, are not created inside the application root element. They are instead placed at the very end of the page structure, right before the </body> element closing. It's done in this way because a single panel can be used by more than one editor instance present in the page (to enhance performance and save resources).

* We avoid using "aria-label", using instead "aria-labelledby". In an ARIA point of view, this is not necessary in most cases, and it even makes the DOM structure and our code more complex, but unfortunately IE has no support for "aria-label".

* The aria-disabled attribute is properly used to indicate buttons and menu options that are disabled.

* We use the <a> element for several UI elements (like buttons, menu items, tabs, etc). In this way we are able to use the :hover CSS pseudo-class, which is not supported in all elements in some browsers.

* The HTML structures illustrated in this page are not complete, including exclusively the elements and attributes that have ARIA relevance or that enhances the structure understanding.

FCKeditor 3.x/Design and Architecture

2010-02-17T13:06:06Z

Fredck: /* The User Interface */

These pages summarize the ideas, concepts, motivations and specifications for the development of CKEditor 3.0 (code name V3). This is the repository into which converge the results of thoughts and discussions placed around our project. It's a place in tranformation, and you are invited to participate, making it move forward.

== The Project ==

*[[FCKeditor 3.x/Design and Architecture/ODE|About the Open Development Effort]]
*[[FCKeditor 3.x/Contributors|Project Contributors]]
*[[FCKeditor 3.x/Design and Architecture/Development Methodology|Development Methodology]]
*[[FCKeditor 3.x/Design and Architecture/Rebranding|Rebranding]]
*[[FCKeditor 3.x/Design and Architecture/License|License]]
*[[FCKeditor 3.x/Design and Architecture/Funding|Funding and Sponsorship]]

== Concepts and Macro Features ==

*[[FCKeditor 3.x/Design and Architecture/Performance|(High) Performance]]<br>
*[[FCKeditor 3.x/Design and Architecture/Browsers Compatibility|Browsers Compatibility]]
*[[FCKeditor 3.x/Design and Architecture/Accessibility|Accessibility]]
*[[FCKeditor 3.x/Design and Architecture/Usability|Usability]]
*[[FCKeditor 3.x/Design and Architecture/Standards|Standards]]
*[[FCKeditor 3.x/Design and Architecture/Semantics|Semantics]]
*[[FCKeditor 3.x/Design and Architecture/Globalization|Globalization]]
*[[FCKeditor 3.x/Design and Architecture/Plugin Based|Plugin Based]]
*[[FCKeditor 3.x/Design and Architecture/Event Driven|Event Driven]]
*[[FCKeditor 3.x/Design and Architecture/DOM Abstraction|DOM Abstraction]]
*[[FCKeditor 3.x/Design and Architecture/Memory Leak|Memory Leak Free]]
*[[FCKeditor 3.x/Design and Architecture/Semantics and Formatting|Semantics and Formatting = Styles]]
*[[FCKeditor 3.x/Design and Architecture/Documentation|Documentation]]
*[[FCKeditor 3.x/Design and Architecture/Loading and Startup|Loading and Startup]]

== Coding ==

*[[FCKeditor 3.x/Design and Architecture/Namespaces|Namespacing]]
*[[FCKeditor 3.x/Design and Architecture/Coding Style|Coding Style]]
*[[FCKeditor 3.x/Design and Architecture/Coding Patterns|Coding Patterns]]
*[[FCKeditor 3.x/Design and Architecture/Native Objects|Native Objects : Untouchable]]
*[[FCKeditor 3.x/Design and Architecture/Testing|Testing]]

== The User Interface ==

*[[FCKeditor 3.x/Design and Architecture/Basic Structure|Basic Structure]]
*[[FCKeditor 3.x/Design and Architecture/Editing Area|Editing Area]]
*[[FCKeditor 3.x/Design and Architecture/Source Area|Source Area]]
*[[FCKeditor 3.x/Design and Architecture/Toolbar|Toolbar]]
*[[FCKeditor 3.x/Design and Architecture/Context Menu|Context Menu]]
*[[FCKeditor 3.x/Design and Architecture/Elements Path|Elements Path]]
*[[FCKeditor 3.x/Design and Architecture/Resize Handle|Resize Handle]]
*[[FCKeditor 3.x/Design and Architecture/Dialog System|Dialogs]]
*[[FCKeditor 3.x/Design and Architecture/ARIA Described|ARIA Described]]

== Editing Features ==

*Undo and Redo
*Cut, Copy and Paste
*Bold, Italic and Underline
*Lists
*Links
*Images
*Block Formatting
*Styles
*...

== Other Features ==

*File Browser
*Spell Checker
*Debugging -- internal debugger (like FCKDebug)

== Output ==

*Default XHTML
*HTML
*Other Formats -- non HTML

== Customization ==

*Configuration
*Skins
*Plugins

== Integration ==

*JavaScript API
*Ajax
*[[FCKeditor 3.x/Design and Architecture/SSI|Server Side Languages and Platforms]]
*JavaScript Libraries and Frameworks
*Targeted Integration Efforts

== Distribution ==

*[[FCKeditor 3.x/Design and Architecture/CKReleaser|Release Building (CKReleaser)]]
*Installation
*Compression and Minification
*Customized Distributions
*Assets Server / CDN
*Proxies, Caches and Updates
*Domain Relaxing
*HTTPS

FCKeditor 3.x/Design and Architecture/Coding Style

2010-02-02T13:23:10Z

Fredck: /* Whitespace */

= Coding Style Guidelines =

These guidelines where defined based on mixed common standards mainly related to Java programming. It aims to reflect the generally accepted standards for JavaScript coding with some minor adjustments.

It is quite common to take the Java style to write JavaScript code, assuming it is a "cut-down" version of Java. Although JavaScript has an indirect relation with Java, apart from the similar "C
== General Recommendations ==

Any violation to the guide is allowed if it enhances readability.

If the name "CKEditor" is used, if must always be written with "CKE" uppercased concatenated with "ditor" in lowercase. The following usages are wrong: "CKeditor", "ckEditor", "CK Editor", etc. Exceptions are made for directories and file names, which must always be lowercased, and the CKEDITOR namespace name.

If the name "FCKeditor" is used, it must always be written with "FCK" uppercased concatenated with "editor" in lowercase. The following are wrong: "FckEditor", "FCKEditor", "fckEditor", "FCK Editor", and so on. Exception is made for directory names, where all chars "should" be in lowercase.

The name "JavaScript" should be written with both the "J" and "S" in uppercase. The following are wrong: "Javascript", "javascript", etc.

== Naming Conventions ==

=== Generic Name Conventions ===

The ROOT namespace has a fixed name: CKEDITOR.
<pre>CKEDITOR
</pre>
Names representing namespaces must be all lowercase.
<pre>CKEDITOR.dom, CKEDITOR.env, CKEDITOR.ui
</pre>
Names representing public classes and public global objects must be in PascalCase.
<pre>CKEDITOR.dom.Document, CKEDITOR.Util
</pre>
Names representing constants must be all UPPERCASE.
<pre>CKEDITOR.STATUS_COMPLETE, CKEDITOR.EDITMODE_WYSIWYG, CKEDITOR.CTRL
</pre>
Names representing public methods must be verbs and written in camelCase.
<pre>appendStyleSheet(), getElement (), setTimeout()
</pre>
Names representing public properties must be nouns and written in camelCase.
<pre>name, document, targetWindow
</pre>
Names representing private methods must be verbs and written in camelCase prefixed with an underscore.
<pre>_doInternalStuff()
</pre>
Names representing private properties must be nouns and written in camelCase prefixed with an underscore.
<pre>_internalCounter, _prefix
</pre>
Abbreviations and acronyms should not be uppercase when used as name.
<pre>setHtml(), XmlDocument
NOT
setHTML(), XMLDocument
</pre>
All names should be written in English.

=== Specific Name Conventions ===

The prefixes "get" and "set" may be used on methods that get or set properties which require computation.
<pre>setArrayCount(), getFormattedValue()
</pre>
The prefix "checkIs" may be used on methods which return boolean states which require computation.
<pre>checkIsValid(), checkIsEmpty()
</pre>
Abbreviations in names should be avoided.
<pre>getDirectoryName(), applicationCommand
NOT
getDirName(), appCmd
</pre>
== Files ==

All files must be named in all lower case.

Classes and global objects should be declared in individual files with the file name matching the class/object name.
<pre>fckbrowserinfo.js, fcktoolbarbutton.js
</pre>
== Layout ==

For indentation, the TAB should be used. Development IDEs should be configured to represent TABs as 4 spaces.
<pre>if ( test )
{
if ( otherTest )
doSomething();
doMore();
}
</pre>
Block layout should be as illustrated.
<pre>while ( !done )
{
doSomething();
done = moreToDo();
}
</pre>
Single statement (single line only) if/else/while/for could (preferably) be written without brackets, but never in the same line.
<pre>if ( condition )
statement;

while ( condition )
statement;

for ( initialization ; condition ; update )
statement;
</pre>
The above rule is not valid for nested blocks, like the following:
<pre>if ( condition )
{
if ( anotherCondition )
statement;
}

// WRONG:
if ( condition )
if ( anotherCondition )
statement;
</pre>
The incompleteness of split lines must be made obvious.
<pre>totalSum = a + b + c +
d + e;

method( param1, param2,
param3 );

setText( 'Long line split' +
'into two parts.' );
</pre>
=== Whitespace ===
"If", "for", "while" and "switch" should be followed by a white space.
<pre>if ( true )
NOT
if( true )
</pre>
Conventional operators should be surrounded by a space (including ternary operators).
<pre>if ( i > 3 && test == 'yes' )
</pre>
Commas should be followed by a space.
<pre>function myFunction( parm1, param2, param3 )
</pre>
Semi-colons in for statements should be surrounded by a space.
<pre>for ( var i = 0 ; i < count ; i++ )
</pre>
Semi-colons should not be preceded by a space.
<pre>doSomething();
var name = 'John';
</pre>
Colons should be surrounded by a space.
<pre>case 100 :
NOT
case 100:
</pre>
Opening parenthesis must be followed by a space and closing parenthesis must be preceded by a space.
<pre>if ( myVar == 1 )
</pre>
There special cases where no space is recommended. When opening parenthesis for a "self-executing anonymous function" and when closing parenthesis after an indented code block:
<pre>(function()
{
// Code here
})();

myMethod( function()
{
// Code here
});
</pre>
Functions/method calls should not be followed by a space.
<pre>doSomething( someParameter );
NOT
doSomething ( someParameter );
</pre>
Logical units within a block should be separated by one blank line.
<pre>// Create a new identity matrix
var matrix = new Matrix4x4();

// Precompute angles for efficiency
var cosAngle = mathCos( angle );
var sinAngle = mathSin( angle );

// Specify matrix as a rotation transformation
matrix.setElement( 1, 1, cosAngle );
matrix.setElement( 1, 2, sinAngle );
matrix.setElement( 2, 1, -sinAngle );
matrix.setElement( 2, 2, cosAngle );

// Apply rotation
transformation.multiply( matrix );
</pre>

Multiple variables declaration in a single "var" statement must be aligned with a single tab.

<pre>
var example = 1,
sample = 2;
NOT
var example = 1,
sample = 2;
</pre>

== Variables ==

Variables must be always defined with "var".

Function parameters must be in camelCase.
<pre>function sum( firstNumber, secondNumber )
</pre>
Local variables must be in camelCase.
<pre>function doSomething()
{
var colorOne = 1;
var colorTwo = 2;

return colorOne + colorTwo;
}
</pre>
Several variables can be defined with a single var statement, but only if their initialization values are in single lines. Do not initialize more than one variable is a single line:
<pre>var aVar, someVar,
other1Var = 10,
other2Var = 25,
isVar = true;

var longVar = function()
{
// This var takes more than one line.
};

var objVar =
{
// This var takes more than one line.
};
</pre>

== Comments ==

Tricky code should not be commented but rewritten: In general, the use of comments should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure.

All comments should be written in English. Whenever possible, end comments with a period as normal phrases, and wrap comments within the first 80 characters of each line.

There should be a space after the comment identifier.
<pre>// This is a comment. NOT: //This is a comment
/** NOT: /**
* This is block *This is a block
* comment. *comment
*/ */
</pre>
Note that comment blocks should be opened with two asterisks only for documentation purposes. See [[FCKeditor 3.x/Design and Architecture/Documentation#JavaScript_API|JavaScript API Documentation]].

== Regular Expressions ==

The '''regular expression literal''' should be used whenever possible, instead of the RegExp object, which should be used only when the regular expression pattern is not constant or depends on runtime computation.
<pre>/^foo\s*/i
NOT
new RegExp( '^foo\s*', 'i' )
</pre>
Other than shortnesses and better readability, regular expression literals are compiled during script evaluation, which improves performance at runtime.

== File Headers ==

There are minimum requirements for us to be able to make our code available to the world. Most of them are related to legal needs, which help us protecting the project from abuses.

Here is a JavaScript template for the header to be included in the source code:
<pre>/*
Copyright (c) 2003-2009, CKSource - Frederico Knabben. All rights reserved.
For licensing, see LICENSE.html or http://ckeditor.com/license
*/
</pre>
Of course, different languages have different commenting syntax, so it is enough to copy the header from an existing file to maintain the style.

=== Author Tags ===

Author names, e-mails or web site addresses should be avoided in the header. To justify that, let me recall a citation from Sander Striker, a member of the Apache Software Foundation, that can be found at [http://producingoss.com/en/managing-volunteers.html#territoriality Producing Open Source Software]:
<blockquote>At the Apache Software foundation we discourage the use of author tags in source code. There are various reasons for this, apart from the legal ramifications. Collaborative development is about working on projects as a group and caring for the project as a group. Giving credit is good, and should be done, but in a way that does not allow for false attribution, even by implication. There is no clear line for when to add or remove an author tag. Do you add your name when you change a comment? When you put in a one-line fix? Do you remove other author tags when you refactor the code and it looks 95% different? What do you do about people who go about touching every file, changing just enough to make the virtual author tag quota, so that their name will be everywhere?<br> </blockquote> <blockquote>
There are better ways to give credit, and our preference is to use those. From a technical standpoint author tags are unnecessary; if you wish to find out who wrote a particular piece of code, the version control system can be consulted to figure that out. Author tags also tend to get out of date. Do you really wish to be contacted in private about a piece of code you wrote five years ago and were glad to have forgotten?<br>
</blockquote>
The SVN is a good place to understand user participation. Even when committing changes proposed by Joe White, it is nice to add a comment like "Thanks to Joe White." in the commit message.

FCKeditor 3.x/Design and Architecture/Coding Style

2010-02-02T13:21:51Z

Fredck: /* Whitespace */

= Coding Style Guidelines =

These guidelines where defined based on mixed common standards mainly related to Java programming. It aims to reflect the generally accepted standards for JavaScript coding with some minor adjustments.

It is quite common to take the Java style to write JavaScript code, assuming it is a "cut-down" version of Java. Although JavaScript has an indirect relation with Java, apart from the similar "C
== General Recommendations ==

Any violation to the guide is allowed if it enhances readability.

If the name "CKEditor" is used, if must always be written with "CKE" uppercased concatenated with "ditor" in lowercase. The following usages are wrong: "CKeditor", "ckEditor", "CK Editor", etc. Exceptions are made for directories and file names, which must always be lowercased, and the CKEDITOR namespace name.

If the name "FCKeditor" is used, it must always be written with "FCK" uppercased concatenated with "editor" in lowercase. The following are wrong: "FckEditor", "FCKEditor", "fckEditor", "FCK Editor", and so on. Exception is made for directory names, where all chars "should" be in lowercase.

The name "JavaScript" should be written with both the "J" and "S" in uppercase. The following are wrong: "Javascript", "javascript", etc.

== Naming Conventions ==

=== Generic Name Conventions ===

The ROOT namespace has a fixed name: CKEDITOR.
<pre>CKEDITOR
</pre>
Names representing namespaces must be all lowercase.
<pre>CKEDITOR.dom, CKEDITOR.env, CKEDITOR.ui
</pre>
Names representing public classes and public global objects must be in PascalCase.
<pre>CKEDITOR.dom.Document, CKEDITOR.Util
</pre>
Names representing constants must be all UPPERCASE.
<pre>CKEDITOR.STATUS_COMPLETE, CKEDITOR.EDITMODE_WYSIWYG, CKEDITOR.CTRL
</pre>
Names representing public methods must be verbs and written in camelCase.
<pre>appendStyleSheet(), getElement (), setTimeout()
</pre>
Names representing public properties must be nouns and written in camelCase.
<pre>name, document, targetWindow
</pre>
Names representing private methods must be verbs and written in camelCase prefixed with an underscore.
<pre>_doInternalStuff()
</pre>
Names representing private properties must be nouns and written in camelCase prefixed with an underscore.
<pre>_internalCounter, _prefix
</pre>
Abbreviations and acronyms should not be uppercase when used as name.
<pre>setHtml(), XmlDocument
NOT
setHTML(), XMLDocument
</pre>
All names should be written in English.

=== Specific Name Conventions ===

The prefixes "get" and "set" may be used on methods that get or set properties which require computation.
<pre>setArrayCount(), getFormattedValue()
</pre>
The prefix "checkIs" may be used on methods which return boolean states which require computation.
<pre>checkIsValid(), checkIsEmpty()
</pre>
Abbreviations in names should be avoided.
<pre>getDirectoryName(), applicationCommand
NOT
getDirName(), appCmd
</pre>
== Files ==

All files must be named in all lower case.

Classes and global objects should be declared in individual files with the file name matching the class/object name.
<pre>fckbrowserinfo.js, fcktoolbarbutton.js
</pre>
== Layout ==

For indentation, the TAB should be used. Development IDEs should be configured to represent TABs as 4 spaces.
<pre>if ( test )
{
if ( otherTest )
doSomething();
doMore();
}
</pre>
Block layout should be as illustrated.
<pre>while ( !done )
{
doSomething();
done = moreToDo();
}
</pre>
Single statement (single line only) if/else/while/for could (preferably) be written without brackets, but never in the same line.
<pre>if ( condition )
statement;

while ( condition )
statement;

for ( initialization ; condition ; update )
statement;
</pre>
The above rule is not valid for nested blocks, like the following:
<pre>if ( condition )
{
if ( anotherCondition )
statement;
}

// WRONG:
if ( condition )
if ( anotherCondition )
statement;
</pre>
The incompleteness of split lines must be made obvious.
<pre>totalSum = a + b + c +
d + e;

method( param1, param2,
param3 );

setText( 'Long line split' +
'into two parts.' );
</pre>
=== Whitespace ===
"If", "for", "while" and "switch" should be followed by a white space.
<pre>if ( true )
NOT
if( true )
</pre>
Conventional operators should be surrounded by a space (including ternary operators).
<pre>if ( i > 3 && test == 'yes' )
</pre>
Commas should be followed by a space.
<pre>function myFunction( parm1, param2, param3 )
</pre>
Semi-colons in for statements should be surrounded by a space.
<pre>for ( var i = 0 ; i < count ; i++ )
</pre>
Semi-colons should not be preceded by a space.
<pre>doSomething();
var name = 'John';
</pre>
Colons should be surrounded by a space.
<pre>case 100 :
NOT
case 100:
</pre>
Opening parenthesis must be followed by a space and closing parenthesis must be preceded by a space.
<pre>if ( myVar == 1 )
</pre>
There special cases where no space is recommended. When opening parenthesis for a "self-executing anonymous function" and when closing parenthesis after an indented code block:
<pre>(function()
{
// Code here
})();

myMethod( function()
{
// Code here
});
</pre>
Functions/method calls should not be followed by a space.
<pre>doSomething( someParameter );
NOT
doSomething ( someParameter );
</pre>
Logical units within a block should be separated by one blank line.
<pre>// Create a new identity matrix
var matrix = new Matrix4x4();

// Precompute angles for efficiency
var cosAngle = mathCos( angle );
var sinAngle = mathSin( angle );

// Specify matrix as a rotation transformation
matrix.setElement( 1, 1, cosAngle );
matrix.setElement( 1, 2, sinAngle );
matrix.setElement( 2, 1, -sinAngle );
matrix.setElement( 2, 2, cosAngle );

// Apply rotation
transformation.multiply( matrix );
</pre>
Second line of a multiple variables declarations should have a single tab proceeded.
<pre>
var example = 1,
sample = 2;
NOT
var example = 1,
sample = 2;
</pre>

== Variables ==

Variables must be always defined with "var".

Function parameters must be in camelCase.
<pre>function sum( firstNumber, secondNumber )
</pre>
Local variables must be in camelCase.
<pre>function doSomething()
{
var colorOne = 1;
var colorTwo = 2;

return colorOne + colorTwo;
}
</pre>
Several variables can be defined with a single var statement, but only if their initialization values are in single lines. Do not initialize more than one variable is a single line:
<pre>var aVar, someVar,
other1Var = 10,
other2Var = 25,
isVar = true;

var longVar = function()
{
// This var takes more than one line.
};

var objVar =
{
// This var takes more than one line.
};
</pre>

== Comments ==

Tricky code should not be commented but rewritten: In general, the use of comments should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure.

All comments should be written in English. Whenever possible, end comments with a period as normal phrases, and wrap comments within the first 80 characters of each line.

There should be a space after the comment identifier.
<pre>// This is a comment. NOT: //This is a comment
/** NOT: /**
* This is block *This is a block
* comment. *comment
*/ */
</pre>
Note that comment blocks should be opened with two asterisks only for documentation purposes. See [[FCKeditor 3.x/Design and Architecture/Documentation#JavaScript_API|JavaScript API Documentation]].

== Regular Expressions ==

The '''regular expression literal''' should be used whenever possible, instead of the RegExp object, which should be used only when the regular expression pattern is not constant or depends on runtime computation.
<pre>/^foo\s*/i
NOT
new RegExp( '^foo\s*', 'i' )
</pre>
Other than shortnesses and better readability, regular expression literals are compiled during script evaluation, which improves performance at runtime.

== File Headers ==

There are minimum requirements for us to be able to make our code available to the world. Most of them are related to legal needs, which help us protecting the project from abuses.

Here is a JavaScript template for the header to be included in the source code:
<pre>/*
Copyright (c) 2003-2009, CKSource - Frederico Knabben. All rights reserved.
For licensing, see LICENSE.html or http://ckeditor.com/license
*/
</pre>
Of course, different languages have different commenting syntax, so it is enough to copy the header from an existing file to maintain the style.

=== Author Tags ===

Author names, e-mails or web site addresses should be avoided in the header. To justify that, let me recall a citation from Sander Striker, a member of the Apache Software Foundation, that can be found at [http://producingoss.com/en/managing-volunteers.html#territoriality Producing Open Source Software]:
<blockquote>At the Apache Software foundation we discourage the use of author tags in source code. There are various reasons for this, apart from the legal ramifications. Collaborative development is about working on projects as a group and caring for the project as a group. Giving credit is good, and should be done, but in a way that does not allow for false attribution, even by implication. There is no clear line for when to add or remove an author tag. Do you add your name when you change a comment? When you put in a one-line fix? Do you remove other author tags when you refactor the code and it looks 95% different? What do you do about people who go about touching every file, changing just enough to make the virtual author tag quota, so that their name will be everywhere?<br> </blockquote> <blockquote>
There are better ways to give credit, and our preference is to use those. From a technical standpoint author tags are unnecessary; if you wish to find out who wrote a particular piece of code, the version control system can be consulted to figure that out. Author tags also tend to get out of date. Do you really wish to be contacted in private about a piece of code you wrote five years ago and were glad to have forgotten?<br>
</blockquote>
The SVN is a good place to understand user participation. Even when committing changes proposed by Joe White, it is nice to add a comment like "Thanks to Joe White." in the commit message.

CKEditor 3.x/Developers Guide/jQuery Adapter

2010-01-19T17:42:09Z

Fredck:

CKEditor offers native jQuery integration through its jQuery Adapter (a jQuery plugin basically). It provides deep integration of CKEditor into jQuery, using its native features.

== Creating editor instances ==

To create editor instances, other than the usual CKEditor core script, you need to load the jQuery Adapter file in the page, in the following order:

<source language="html"><script type="text/javascript" src="/ckeditor/ckeditor.js"></script>
<script type="text/javascript" src="/ckeditor/adapters/jquery.js"></script></source>

At this point, any textarea, p or div element can be transformed into a rich text editor by simply using the ckeditor() method:
<source language="js">$( 'textarea.editor' ).ckeditor();</source>
jQuery chaining can also be used:
<source language="js">$( '.section-x' )
.find( 'textarea.editor' )
.ckeditor()
.end()
.find( 'a' )
.addClass( 'mylink' )
.end();</source>

The ckeditor() is the main method in the jQuery adapter. It accepts two optional parameters:
* A '''callback function''' to be execute when the editor is ready.
* '''Configuration options''' specific to the created editor instance.

The [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html configurations options] are passed through a simple object containing properties, each one related to a specific editor setting.</p>
<source language="js">$('.jquery_ckeditor')
.ckeditor( function() { /* callback code */ }, { skin : 'office2003' } );
.ckeditor( callback2 );</source>

Code above won't create 2 editors - it will discover that one is already during creation and wait with the second callback. Each of those callbacks will be executed in context of the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object (so "this" will be the editor) and the DOM element object will be passed as parameter.

== Code interaction with editor instances==
As soon as an editor instance is ready (after the above callback call), the ckeditorGet() method can then be used to retrieve a [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object that represents an editor instance. For example:
<source language="js">var editor = $('.jquery_ckeditor').ckeditorGet();
alert( editor.checkDirty() );
</source>

Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides the dedicated val() method:
<source language="js">// Get the editor data.
var data = $( 'textarea.editor' ).val();
// Set the editor data.
$( 'textarea.editor' ).val( 'my new content' );</source>

This feature can be disabled by setting CKEDITOR.config.jqueryOverrideVal to false, before loading the adapter code.

For textareas, the editor will automatically return it's content back to the form when it is submitted. CKEditor also works with the official [http://jquery.malsup.com/form/ jQuery Form Plugin] for AJAX based forms. It doesn't require anything from the developer side.

== Events handling ==
Although CKEditor uses its own event system, there are four main events which we're exposing to the jQuery event system. All events use the event namespace, which is simply named ".ckeditor".

The following events are available:
* <strong>instanceReady.ckeditor</strong>: fired when the editor is created, but before any callback being passed to the ckeditor() method.
* <strong>setData.ckeditor</strong>: fired when data is set into the editor.
* <strong>getData.ckeditor</strong>: fired when data is fetched from the editor. The current editor data is also passed in the arguments.
* <strong>destroy.ckeditor</strong>: fired when the editor gets destroyed. It can be used, for example, to execute some cleanup on the page.

The editor instance is always passed as the first data argument for the listener. Both getData and setData are often used internally so listening to them should be done with care.

jQuery events DO bubble up through the DOM, so they can be listened selectively on certain parts of the document.

CKEditor 3.x/Developers Guide/Integration/jQuery Adapter

2010-01-19T17:39:11Z

Fredck: moved CKEditor 3.x/Developers Guide/Integration/jQuery Adapter to CKEditor 3.x/Developers Guide/jQuery Adapter

#REDIRECT [[CKEditor 3.x/Developers Guide/jQuery Adapter]]

CKEditor 3.x/Developers Guide/jQuery Adapter

2010-01-19T17:39:11Z

Fredck: moved CKEditor 3.x/Developers Guide/Integration/jQuery Adapter to CKEditor 3.x/Developers Guide/jQuery Adapter

The CKEditor jQuery Adapter provides deep integration into the jQuery JavaScript Library of the CKEditor, using native library's features.

== Creating editor instances ==
To create editor instances, other than the usual CKEditor core script, you need to load the jQuery Adapter file in the page, in the following order:

<source language="html"><script type="text/javascript" src="/ckeditor/ckeditor.js"></script>
<script type="text/javascript" src="/ckeditor/adapters/jquery.js"></script></source>

At this point, any textarea, p or div element can be transformed into a rich text editor by simply using the ckeditor() method:
<source language="js">$( 'textarea.editor' ).ckeditor();</source>
jQuery chaining can also be used:
<source language="js">$( '.section-x' )
.find( 'textarea.editor' )
.ckeditor()
.end()
.find( 'a' )
.addClass( 'mylink' )
.end();</source>

The ckeditor() is the main method in the jQuery adapter. It accepts two optional parameters:
* A '''callback function''' to be execute when the editor is ready.
* '''Configuration options''' specific to the created editor instance.

The [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html configurations options] are passed through a simple object containing properties, each one related to a specific editor setting.</p>
<source language="js">$('.jquery_ckeditor')
.ckeditor( function() { /* callback code */ }, { skin : 'office2003' } );
.ckeditor( callback2 );</source>

Code above won't create 2 editors - it will discover that one is already during creation and wait with the second callback. Each of those callbacks will be executed in context of the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object (so "this" will be the editor) and the DOM element object will be passed as parameter.

== Code interaction with editor instances==
As soon as an editor instance is ready (after the above callback call), the ckeditorGet() method can then be used to retrieve a [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object that represents an editor instance. For example:
<source language="js">var editor = $('.jquery_ckeditor').ckeditorGet();
alert( editor.checkDirty() );
</source>

Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides the dedicated val() method:
<source language="js">// Get the editor data.
var data = $( 'textarea.editor' ).val();
// Set the editor data.
$( 'textarea.editor' ).val( 'my new content' );</source>

This feature can be disabled by setting CKEDITOR.config.jqueryOverrideVal to false, before loading the adapter code.

For textareas, the editor will automatically return it's content back to the form when it is submitted. CKEditor also works with the official [http://jquery.malsup.com/form/ jQuery Form Plugin] for AJAX based forms. It doesn't require anything from the developer side.

== Events handling ==
Although CKEditor uses its own event system, there are four main events which we're exposing to the jQuery event system. All events use the event namespace, which is simply named ".ckeditor".

The following events are available:
* <strong>instanceReady.ckeditor</strong>: fired when the editor is created, but before any callback being passed to the ckeditor() method.
* <strong>setData.ckeditor</strong>: fired when data is set into the editor.
* <strong>getData.ckeditor</strong>: fired when data is fetched from the editor. The current editor data is also passed in the arguments.
* <strong>destroy.ckeditor</strong>: fired when the editor gets destroyed. It can be used, for example, to execute some cleanup on the page.

The editor instance is always passed as the first data argument for the listener. Both getData and setData are often used internally so listening to them should be done with care.

jQuery events DO bubble up through the DOM, so they can be listened selectively on certain parts of the document.

CKEditor 3.x/Developers Guide

2010-01-19T17:38:47Z

Fredck:

{{#CUSTOMTITLE:CKEditor 3.x - Developer's Guide}}

*[[CKEditor 3.x/Developers Guide/Installation|Installation]]
* Integration
**[[CKEditor 3.x/Developers Guide/Integration|Integration]]
** [[CKEditor 3.x/Developers Guide/jQuery Adapter|jQuery]]
*Configuration
**[[CKEditor 3.x/Developers Guide/Setting Configurations|Setting Configurations]]
**[[CKEditor 3.x/Developers Guide/Toolbar|Toolbar]]
**[[CKEditor_3.x/Developers_Guide/Styles|Styles]]
**[[CKEditor 3.x/Developers Guide/Output Formatting|Output Formatting]]
**[[CKEditor 3.x/Developers Guide/Templates|Templates]]
**Spell Checker
**[[CKEditor 3.x/Developers Guide/File Browser (Uploader)|File Browser/Uploader ]]
*Customization
**Plugins
**Skins
*Advanced Tasks
**[[CKEditor_3.x/Developers_Guide/Editor_Core_URLs_Manipulation|Editor Core URLs Manipulation]]
*Deployment
*[http://docs.cksource.com/ckeditor_api/ JavaScript API]
*[[FCKeditor 3.x/Design and Architecture|Design and Architecture]]

CKEditor 3.x/Developers Guide

2010-01-16T14:10:36Z

Fredck:

{{#CUSTOMTITLE:CKEditor 3.x - Developer's Guide}}

*[[CKEditor 3.x/Developers Guide/Installation|Installation]]
*[[CKEditor 3.x/Developers Guide/Integration|Integration]]
*Configuration
**[[CKEditor 3.x/Developers Guide/Setting Configurations|Setting Configurations]]
**[[CKEditor 3.x/Developers Guide/Toolbar|Toolbar]]
**[[CKEditor_3.x/Developers_Guide/Styles|Styles]]
**[[CKEditor 3.x/Developers Guide/Output Formatting|Output Formatting]]
**[[CKEditor 3.x/Developers Guide/Templates|Templates]]
**Spell Checker
**[[CKEditor 3.x/Developers Guide/File Browser (Uploader)|File Browser/Uploader ]]
*Customization
**Plugins
**Skins
*Advanced Tasks
**[[CKEditor_3.x/Developers_Guide/Editor_Core_URLs_Manipulation|Editor Core URLs Manipulation]]
*Deployment
*[http://docs.cksource.com/ckeditor_api/ JavaScript API]
*[[FCKeditor 3.x/Design and Architecture|Design and Architecture]]

CKEditor 3.x/Developers Guide/Editor Core URLs Manipulation

2010-01-16T14:06:26Z

Fredck: Created page with 'CKEditor has been built with customization and flexibility in mind. These aspects have also being considered for its most basic aspects, like its installation files location, whi…'

CKEditor has been built with customization and flexibility in mind. These aspects have also being considered for its most basic aspects, like its installation files location, which can be also fully customized.

== The Files Loaded from the Server ==

To create editor instances in a page, developers must [[CKEditor_3.x/Developers_Guide/Integration|include the ckeditor.js file]] into it. This file contains the core code of the editor. It creates editors in the page, and automatically loads all necessary files to make them run. The following is a list of files that are generally loaded:

* Configurations file.
* Skin files, which include CSS and eventually JavaScript.
* Language files.
* Plugin files.
* Dialog files.
* etc...

In a standard installation, not all the above files are loaded and all of them are located inside the CKEditor installation folder. Other installations may load files from other folders also, depending on the configurations and customizations.

While the path and the file name of some of the editor files are customizable (like [[CKEditor_3.x/Developers_Guide/Setting_Configurations|configuration files]]), others are quite standard and fixed. For example, the English language files will always come from the "lang" folder, with file name en.js, while the main skins file for the Kama skin comes from "skins/kama/editor.css".

== Understanding the Files Loading ==

By default, the editor core code uses the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.html#.getUrl CKEDITOR.getUrl] function to load files. This function transforms editor relative paths into full URLs pointing to resources in the server. Additionally, it appends the editor timestamp to the URL querystring, providing the anti-cache feature.

For example, calling CKEDITOR.getUrl('lang/en.js') returns "<nowiki>http://www.example.com/ckeditor/lang/en.js?t=A067</nowiki>", if using CKEditor 3.1, installed in the "/ckeditor" folder of the www.example.com web site.

== Manipulating URLs ==

CKEditor offers a simple way to manipulate the results of the CKEDITOR.getUrl function. It's enough to define a global '''CKEDITOR_GETURL''' function in the page. This function will be called by CKEDITOR.getUrl. If anything is returned from it, it will be used as the resolved URL, otherwise the default resolution procedure is used.

For example, the following function sends all language file requests to a PHP script, passing the language code to it. The script could then take the language file code from a database:

<pre>
<script type="text/javascript">

function CKEDITOR_GETURL( resource )
{
var match = resource.match( /lang\/([a-z\-]+)\.js$/ );
if ( match )
return '/getlang.php?lang=' + match[ 1 ];
}

</script>
<script type="text/javascript" src="/ckeditor/ckeditor.js"></script>
</pre>

In this example, only the language files will be resolved by our function. All other files will have pass though the default resolution process.

Note that '''the CKEDITOR_GETURL function must be defined before the ckeditor.js loading''', otherwise it will be ignored. The above code can be included at the top of the ckeditor.js file also.

== Usage Cases ==

There are several cases that may benefit from this feature. Here we have a list of few of them:

* Point editor core files to be loaded from different directories with different names. For example having the English language file coming from "/mylangfiles/lang_en.js".
* Having all editor files being served by a server process (like loading from the database), instead of having them physically installed.
* Some server applications may avoid directories structures. For example, we could have the English language files renamed to "lang_en.js" and a skin file to "skin_kama_editor.css" (all slashes replaced by underscores).
* etc...

CKEditor 3.x/Developers Guide/Templates

2009-12-30T16:08:28Z

Fredck: Created page with 'With CKEditor, content writers can select a template from a list by clicking the "Templates" button in the toolbar. A template is a predefined piece of HTML that is placed inside…'

With CKEditor, content writers can select a template from a list by clicking the "Templates" button in the toolbar. A template is a predefined piece of HTML that is placed inside the editor. In this way the user doesn't need to start writing from scratch. Designers can prepare well designed templates, avoiding user errors before they happen.

=== Template Definition Files ===

The editor comes with three sample templates that are there just to show the way it works. They are defined into the "plugins/templates/templates/default.js" file.

Developers should definitely change the default templates as they are not especially useful to end users.

Note that a template definition file is a JavaScript file that's loaded when opening the templates dialog for the first time. This file may be changed to include custom templates, or even better, you can create a separated template file outside the editor installation directory, configuring the editor to use it.

=== Pointing the Editor to a Custom Templates Definitions File ===

Assuming you have created a custom Templates Definitions file named "mytemplates.js" (starting from a copy of default.js) and have placed it into the root of your web site. Now, just add the following setting in the editor configuration:

<pre>
config.templates_files = [ '/mytemplates.js' ];
</pre>

Note that the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.templates_files templates_files] setting is an array, which means that more than one templates file can be used.

=== The Templates Definitions File Contents ===

This is a sample Template Definition file that defines two simple templates:

<pre>
// Register a templates definition set named "default".
CKEDITOR.addTemplates( 'default',
{
// The name of sub folder which hold the shortcut preview images of the templates.
imagesPath : CKEDITOR.getUrl( CKEDITOR.plugins.getPath( 'templates' ) + 'templates/images/' ),

// The templates definitions.
templates :
[
{
title: 'My Template 1',
image: 'template1.gif',
description: 'Description of my template 1.',
html:
'<h2>Template 1</h2>' +
'<p><img scr="/logo.png" style="float:left" />Type the text here.</p>'
},
{
title: 'My Template 2',
html:
'<h3>Template 2</h3>' +
'<p>Type the text here.</p>'
}
]
});
</pre>

As we can see here, the above is pure JavaScript code. It's a simple call to the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.html#.addTemplates CKEDITOR.addTemplates] function, which registers the templates under a unique name ("default"). This name can be then used by the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.templates templates] setting.