Revision as of 17:08, 30 December 2009

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:

config.templates_files = [ '/mytemplates.js' ];

Note that the 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:

// 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>'
			}
		]
});

As we can see here, the above is pure JavaScript code. It's a simple call to the CKEDITOR.addTemplates function, which registers the templates under a unique name ("default"). This name can be then used by the templates setting.