CKEditor Configuration Files

GetSimple-CKEditor comes with a default configuration file and with a default stylesheet-file (for the styles-combobox). You can define your own configuration files which will not be overwritten by GetSimple-Upgrades and which offer some features which are not needed in a standard, stripped-down version.

Standard Configuration File

The standard configuration file, which comes with every GetSimple-Version, is located in the folder yourGetSimpleRoot/admin/template/js/ckeditor and is nearly empty.

It contains only 2 editor-options:

CKEDITOR.editorConfig = function( config )
{
	// Define changes to default configuration here. For example:
	config.removePlugins = 'elementspath,resize' ; // hide element path and resizer
	config.toolbarCanCollapse = false; // hide toolbar collapse button
};

Of couse you could add your additional options here but this file will be overwritten with each update. So better define your own configuration file in a safer location.

Custom Configuration File

To define your customized configuration file is an advantage of CKEditor.

Why do you need such a file? As you saw already, you define a lot of options in the gsconfig.php, so what?

There are some reasons:

  • you want quite a lot of options and it is more comfortable to do this in config.js than in the gsconfig.php
  • you want to define more than options, for example extended dialogues
  • you want to define the HTML-output of the formatter

Here comes your custom configuration. This file is a plain javascript-file.

  1. Take the config.js which comes with GetSimple and rename it, save it in the data- or theme-folder.
  2. edit it and upload it to the desired location at your webserver, check the filepermissions (it must be readable)
  3. define the name and the location of this custom-config-file in the gsconfig.php / EditorOptions

An example:

define('GSEDITOROPTIONS', "entities : false,customConfig : '../../../../theme/yourtheme-folder/yourconfigfile.js',skin: 'v2'
");

This option defines that the custom-config-file with the name yourconfigfile.js is located in the folder of your active theme.

Another option could be:

define('GSEDITOROPTIONS', "entities : false,customConfig : '../../../../data/editorconfig/yourconfigfile.js',skin: 'v2'
");

For this you must create the folder editorconfig in your data-directory and upload the file to that folder. And allow check the .htaccess that js-files are allowed in the data-directory.

Example file:

/*
Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
For licensing, see LICENSE.html or http://ckeditor.com/license
*/
CKEDITOR.editorConfig = function( config )
{
	// Define changes to default configuration here. For example:
	config.toolbarCanCollapse = true,
	config.enterMode = CKEDITOR.ENTER_P,
	config.shiftEnterMode = CKEDITOR.ENTER_BR,
	config.colorButton_enableMore = true,
  	config.bodyId = 'content',
	config.entities = false,
	config.forceSimpleAmpersand = false,
	config.fontSize_defaultLabel = '12px',
	config.font_defaultLabel = 'Arial',
	config.emailProtection = 'encode',
	config.contentsLangDirection = 'ltr',
	config.language = 'en',
	config.contentsLanguage = 'en',
	config.toolbarLocation = 'top',
	config.browserContextMenuOnCtrl = false,
	config.image_previewText = CKEDITOR.tools.repeat('Get-Simple - the best CMS for your purposes. Install it, test it, enjoy it. Free, OpenSource and userfriendly', 50 )
		};
// from  http://help.pixelandtonic.com/brandonkelly/topics/how_do_i_set_output_formatting_writer_rules?from_gsfn=true 
CKEDITOR.on( 'instanceReady', function( ev ) {

var blockTags = ['div','h1','h2','h3','h4','h5','h6','p','pre','ul','li'];
var rules = {
indent : false,
breakBeforeOpen : false,
breakAfterOpen : false,
breakBeforeClose : false,
breakAfterClose : true
};

for (var i=0; i<blockTags.length; i++) {
ev.editor.dataProcessor.writer.setRules( blockTags[i], rules );
}

});

// from  http://docs.cksource.com/CKEditor_3.x/Developers_Guide/Dialog_Customization

CKEDITOR.on( 'dialogDefinition', function( ev )
	{
		// Take the dialog name and its definition from the event data.
		var dialogName = ev.data.name;
		var dialogDefinition = ev.data.definition;
 
		// Check if the definition is from the dialog we're
		// interested on (the Link dialog).
		if ( dialogName == 'link' )
		{
			/* Enable this part only if you don't remove the 'target' tab in the previous block. */
 			FCKConfig.DefaultLinkTarget = '_blank'
			// Get a reference to the "Target" tab.
			var targetTab = dialogDefinition.getContents( 'target' );
			var targetField = targetTab.get( 'linkTargetType' );
			targetField[ 'default' ] = '';
			linkField[ 'default' ] = 'URL';

		} // end dialogDefinition
 
		if ( dialogName == 'image' )
		{
		 dialogDefinition.removeContents( 'advanced' );
		dialogDefinition.removeContents( 'Link' );
		}
 
		if ( dialogName == 'flash' )
		{
					dialogDefinition.removeContents( 'advanced' );
		}
 
	});

Standard Stylesheet

ckeditorstylecombo.jpgVery often, users do not want to use the styles which come by default in the style-combo-box. They want to have another choice.

By default, the stylesheet which defines the contents of the dropdown-list, is called default.js and is located in the folder yourGetSimpleRootDirectory/admin/template/js/ckeditor/plugins/styles/styles/default.js

You can edit this file, but as it is a compressed file, this will be no real pleasure, and, what is more important, this file will be overwritten with every upgrade.

So it is much more handy to define your own stylesheet-configuration and store it at a save location.

Custom Stylesheet

Here are the steps to install your custom stylesheet in short.

  1. get an umcompressed copy of the default stylesheet here from CKEditor's homepage
  2. name this file whatever and upload it to a secure place, for example into the data- or the theme-folder
  3. now edit the gsconfig.php and re-upload it to your server.

Now with more details:

  • you need the advanced editor-toolbar to use the styles-combo-box. If you have not done yet, activate that toolbar.
    define('GSEDITORTOOL', 'advanced');
  • add the stylesheet-definition to the Editor-Options:
define('GSEDITOROPTIONS',"stylesSet: 'default:http://www.yourdomain.de/getsimple-root/themes/ckeditorstyles.js'");

Now, what to edit in this file?

The CKEditor-Styleset contains definitions for the following styles:

  • Block-Styles (already defined, but can be overwritten)
  • Inline-Styles
  • Object-Styles

Define the category for the element you want to add here and edit the file at the relevant place. The syntax:

	{ name : 'Computer Code', element : 'code' },

or

{ name : 'Marker: Yellow', element : 'span', styles : { 'background-color' : 'Yellow' } },

or even

{
		name : 'Image on Left',
		element : 'img',
		attributes :
		{
			'style' : 'padding: 5px; margin-right: 5px',
			'border' : '2',
			'align' : 'left'
		}
	},

One definition must contain at least 2 parameters: name and element. You are free to set the name to whatever you want. element stands for the HTML-element which will be added to the HTML-Output, when you mark some text in the editor and activate this style.

So with these definitions you can add often used formats with an explanatory name to the dropdown-list (and you can delete those which only annoy and are never used).

If you want to add HTML-attributes to the elements in the style-combo, you need the third parameter attributs e.g.

{ name : 'Tablecell top', element : 'td', attributes : { 'valign' : 'top' } },

for CSS-styles, you use the parameter styles. E.g.

{ name : 'Red table', element : 'table', styles : { 'background-color':'red' } },


HTML or XHTML output ?

CKEditor by default wraps the content using XHTML tags (every tag has to be enclosed), and in such way formats it.
To get rid of / in closing tags (to achieve for example <br> [HTML] instead of <br /> [XHTML]) upon saving page ,
you need to edit CKE's config.js file located in admin/template/js/ckeditor/ , and add below code:

CKEDITOR.on( 'instanceReady', function( ev )
    {
        ev.editor.dataProcessor.writer.selfClosingEnd = '>';
    });