Plugins and FCKeditor (1-Introduction)

I'm gonna try to explain how to create and use plugins with FCKeditor.

What's a plugin

The first step would be to understand what is a plugin with regards to FCKeditor. A plugin is basically a javascript file that it's loaded alongside the main FCKeditor code, so you can extend or change some functionality without the need to change the core files. This way you can keep new functionality separated from the main code and upgrades are easier.

With a plugin you can add a new button to the toolbar, new comboboxes, change the interface somehow or even apparently don't do anything, just add some JS code

Every plugin will be based on a directory, and that directory must have a file named fckplugin.js, by default the directory must be placed under the 'editor/plugins/' folder (there are several ones in the default install, go and check them, they can provide lots of info as they are working plugins with all the code, you just need to add them to your editor)

How to add some plugins

To add a plugin to your editor you just need to specify the folder name in your config. By default you can find a commented line that shows how to load the autogrow plugin: // FCKConfig.Plugins.Add( 'autogrow' ) ; remove the comments(//), clear the cache of your browser and reload the editor. Now it should grow automatically as you enter more content until it reach the FCKConfig.AutoGrowMax limit.

Usually you want to add new buttons to the toolbar, in that case you need two steps to add the plugin.

The first one is to load the plugin, this time the PlaceHolder FCKConfig.Plugins.Add( 'placeholder', 'en,it,de,fr' ) ; As we can see here, a plugin can have different languages available. In that case the function must be called first with the name of the folder, and then a comma separated string of the languages available (each one is a .js file under the /lang/ folder of that plugin), the editor will try to load the one that matches the user language or the English one by default.

The second step to add the button is to add the command provided by the plugin to the toolbar that you want to use. The name of the command doesn't have to match the folder, and a plugin can contain more than a single command.

In this case we can modify the toolbar this way: FCKConfig.ToolbarSets["Default"] = [ ['Placeholder', 'Source','DocProps','-','Save','NewPage','Preview','-','Templates'], ['Cut','Copy','Paste','PasteText','PasteWord','-','Print','SpellCheck'], ['Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'], ['Form','Checkbox','Radio','TextField','Textarea','Select','Button','ImageButton','HiddenField'], '/', ['Bold','Italic','Underline','StrikeThrough','-','Subscript','Superscript'], ['OrderedList','UnorderedList','-','Outdent','Indent','Blockquote'], ['JustifyLeft','JustifyCenter','JustifyRight','JustifyFull'], ['Link','Unlink','Anchor'], ['Image','Flash','Table','Rule','Smiley','SpecialChar','PageBreak'], '/', ['Style','FontFormat','FontName','FontSize'], ['TextColor','BGColor'], ['FitWindow','ShowBlocks','-','About'] // No comma for the last row. ] ;

Now do the same routine: save, clear the cache and reload the editor. If you see the new button as the first item, then everything is fine. If you have an error "Unknown toolbar item 'Placeholder'", then it means that you have written something wron:

  1. Check the case it must match the folder name to load the plugin and the command name to add it to the toolbar.
  2. Check that the placeholder folder is under your plugins folder.
  3. Try to check the server logs to verify that the placeholder/fckplugin.js file is correctly loaded (you can also check it with Firebug under the Net tab, or with Fiddler)

Now you have your new button in FCKeditor. You can use the Placeholder command just like the rest of commands, and from that code you can try to create your own ones.

Further reading: Analysis of a plugin at FCKeditor's wiki, repository of FCKeditor's plugins at Sourceforge.

No comments: