 |
Zugg
MASTER
Joined: 25 Sep 2000
Posts: 23379
Location: Colorado, USA
|
 Posted: Fri Oct 29, 2010 6:10 pm
CKEditor Syntax Highlighting for Drupal
|
I've been spending a lot of time on the new www.tessh.com web site for the TeSSH Telnet and SSH client. In addition to providing a place for buying, support, and discussions about TeSSH, this new web site is also acting as a test bed for the eventual new zuggsoft.com web site.
The www.tessh.com site uses the Drupal CMS. Drupal is a very robust and extensible CMS and I've really loving it compared to the MX-Portal/PHPBB mess that we currently have on zuggsoft.com. One of the advantages of Drupal is there are hundreds of contributed modules available for free. One of the disadvantages is there are hundreds of modules available and sometimes it's difficult to determine which to use.
This past week I have been working on getting the Forums and Advanced Forums modules to work more like the PHPBB forum were are all used to. But I also want to enhance the new forums as much as possible. One of the enhancements is to add a WYSIWYG editor for making forum posts.
Using WYSIWYG editors is a bit controversial. Power users tend to hate them because they get in the way. But they are great for novice users who want to do some simple highlighting of their post. The current PHPBB forums use BBCode instead of HTML for highlighting, and I needed to support that on the new site so I can eventually transfer all of the existing posts from the current forums to the new ones. The BBCode module for Drupal handles that just fine.
So why have a WYSIWYG in addition to BBcode? Again, for novice users. So the new forum supports both. That works just fine for simple formatting, but now I wanted to make posting CODE snippets easier. In BBcode we have the [code] tag, so I wanted to still support that. But I also wanted a button in the WYSIWYG editor toolbar for posting code.
Choosing a WYSIWYG editor module for Drupal
The first step was choosing the editor. In the past I've used the Drupal Wysiwyg module since it supports many different editors. But I haven't been very happy with how it integrates with some of the editors. It allows you to select what editor buttons are visible, but not change the order of the toolbar buttons. And plugins for editors can be difficult. So I decided not to use the Wysiwyg module in this case since the Tessh.com site will only have a single editor anyway.
It seemed that the most supported editor was the CKeditor (formerly FCKeditor). I installed the CKEditor module for Drupal and copied the ckeditor.config.js config file into my theme directory. In the CKEditor config settings, you need to set the "Load ckeditor.config.js from theme path" to Yes in the Advanced settings.
The only other CKEditor preferences that I changed were the behavior of the Enter and Shift-Enter keys. This is also a bit controversial, but with PHPBB, users are used to pressing Enter to get a *single* line break and not a full paragraph break. So I changed Enter to use BR and Shift-Enter to use P. This also helps when entering code within the BBcode [code] tag: you don't want the Enter key to insert paragraph breaks within the [code] tag.
Getting BBcode working
Even with the change to the Enter key, the [code] tag was still displaying the HTML BR tags. So I was forced to edit the bbcode-filter.inc file in the bbcode module. Within the _bbcode_filter_process routine there is a line that looks like this:
| Code: |
| $code_tag[1] = str_replace(array('<', '>'), array('& lt;', '& gt;'), $code_tag[1]); |
I simply added the following additional line after it:
| Code: |
| $code_tag[1] = preg_replace('#& lt;br(\s*\/)?& gt;#i', '', $code_tag[1]); |
This strips the BR tags. So now [code] works.
NOTE: There is a problem with this Blog forum when putting & lt; into a post. I need to put a space between the & and lt; characters or else this blog converts it to a < character. So in the above code lines, you need to remove this extra space after the & character for it to work.
Adding a Code button to the CKEditor
The next step was to add a button to the CKEditor toolbar for inserting code. Since I know that I eventually want to add support for Syntax Highlighting, I choose a CKEditor plugin called ckeditor-syntaxhight. This plugin adds a Code button to the toolbar which opens a dialog box for pasting the raw code that you wish to insert. It has support for Alex Gorbatchev's SyntaxHighlighter which I'll talk about more in the next section.
What I really liked about this plugin compared to many others that I tried is that it works just like novice users would expect. If you want to insert code, you click the Code button, enter/paste the code, then click OK. If the code has already been inserted (or anything within HTML PRE tags), you just put the cursor somewhere in the existing code and click the Code button to edit it. The existing code is loaded into the dialog allowing you to change it. Then click OK to save the changes. Or, you can just simply change the existing code directly without the dialog.
The code that is inserted into the post just uses normal HTML PRE tags. The language for syntax highlighting is set using the CLASS attribute. Using the PRE tag is great since browsers won't parse the code within them. And unlike the TinyMCE editor, CKEditor doesn't screw up if you put HTML tags within the PRE tags.
Adding a plugin to CKEditor
The SyntaxHighlight plugin is for CKEditor. The Drupal CKEditor module handles plugins a bit differently. I suppose you could install the plugin into the actual ckeditor folder (not the ckeditor Drupal module, but in sites\all\modules\ckeditor\ckeditor). But I prefer to put site-specific plugins into the Drupal CKeditor plugin folder (sites\all\modules\ckeditor\plugins) so that I can more easily update the base editor library at a later time.
There are two steps to adding a new plugin to the CKEditor module:
1) First, copy the plugin into the sites\all\modules\ckeditor\plugins directory. In this case the plugin directory is sites\all\modules\ckeditor\plugins\syntaxhighlight
2) Next, edit the ckeditor.config.js file that we previously copied to our Drupal theme directory. There are three things we need to edit in this file:
2a) First we add the name of the plugin to the config.extraPlugins variable. Around line 24 you should see a line like this:
| Code: |
| config.extraPlugins += (config.extraPlugins ? ',drupalbreaks' : 'drupalbreaks' ); |
Just copy this line and add your new plugin name, like this:
| Code: |
config.extraPlugins += (config.extraPlugins ? ',drupalbreaks' : 'drupalbreaks' );
config.extraPlugins += (config.extraPlugins ? ',syntaxhighlight' : 'syntaxhighlight' ); |
2b) It isn't enough to just add the plugin name. You also need to tell Drupal where to find the plugin files. Without this step you'll just get a blank white frame where the editor is supposed to be displayed. Down towards the bottom of the file you'll see a line like this (around 115):
| Code: |
| CKEDITOR.plugins.addExternal('drupalbreaks', Drupal.settings.ckeditor.module_path + '/plugins/drupalbreaks/'); |
Once again, copy this line and add our new plugin. So now we have this:
| Code: |
CKEDITOR.plugins.addExternal('drupalbreaks', Drupal.settings.ckeditor.module_path + '/plugins/drupalbreaks/');
CKEDITOR.plugins.addExternal('syntaxhighlight', Drupal.settings.ckeditor.module_path + '/plugins/syntaxhighlight/'); |
2c) Finally, we need to add the Code button to one of our toolbar profiles. In my case, I wanted to add it to the end of the DrupalFull toolbar, but you can put it anywhere you'd like. Just find one of the config.toolbar_xxx lines and add ['Code'] to the list of buttons. For example, the last line for config.toolbar_DrupalFull looks like this:
| Code: |
| ['DrupalBreak', 'DrupalPageBreak'], ['Code'] |
That's it. When you reload a page containing the CKeditor wysiwyg you should see the new Code button. Click it and it should open the dialog for pasting code.
Syntax Highlighting
I really wanted to add syntax highlighting for zScript to the new forums. There are a couple of choices for handling syntax highlighting within a wysiwyg editor. You can use "server side" or "client site" processing.
For "server side", the PHP script on the server is responsible for highlighting the code and inserting the appropriate HTML color tags in the output. This method is used by the GeSHi Generic Syntax Highlighter. This is a nice library, and there are some Drupal plugins for it such as GeSHi Filter. There is also a good blog article by Peter Petrik that gives some details on integration of GeSHi into Drupal and CKeditor.
By the way, Peter Petrik's blog article leaves out a very important step when installing a CKeditor plugin into the Drupal CKeditor module. It isn't enough to just add the name of the plugin to the config.extraPlugins variable as shown in his blog. You also need to tell Drupal where to find this plugin. Otherwise the editor frame will just be blank. You need the line mentioned in the previous section with CKEDITOR.plugins.addExternal.
There are several issues with "server side" syntax highlighting. My biggest issue is that when you copy/paste the code in the web browser, you are getting all of the HTML color tags added by the server. It also doesn't integrate very well with the existing [code] tag in BBcode. Finally, none of the CKeditor plugins for GeSHi that I could find worked the way I wanted them. They don't use a popup dialog for inserting the code...they just change the markup within the main editor panel, which ends up with more problems with HTML BR tags and also HTML SPAN tags. Apparently displaying the SPAN tags is a bug in the more recent CKeditor and you have to downgrade to v3.1 to fix it. I didn't like that solution at all.
Fixing this with "Client side" highlighting
With "client side" syntax highlighting, the server just outputs the normal HTML PRE tag and the highlighting is done via Javascript in the browser. I like this method because it keeps the output of code from the server simple and standard...just HTML PRE tags. So copy/pasting the code just gives the code. It's also better for indexers like Google. You only need the syntax highlighting when looking at the code within the browser...the colors are just for humans and not machines. Since the TeSSH web site requires Javascript for many other parts of the site, this was not an issue for me.
The best "client side" syntax highlighting is the before mentioned: Alex Gorbatchev's SyntaxHighlighter. We already installed the Drupal plugin for this when adding the Code button to CKeditor. So now all we need is the Drupal SyntaxHighlighter module. Download and install just any other Drupal module. Follow the instructions to download and install Alex's syntaxhighligher library into your sites\all\libraries directory.
I am not using the actual SyntaxHighlighter Input filter. I just wanted this module to handle properly loading the Javascript files for the SyntaxHighlighter library.
The nice side effect of using "client side" highlighting is that it works with the existing [code] BBcode tags. By default you won't get any highlighting, so you need to add the proper Class name to the PRE tag. Back in the bbcode-filter.inc file, I found the line that looked like this (line 25):
| Code: |
| $pre[$i++] = '<pre class="bb-code-block">'. $code_tag[1] .'</pre>'; |
and changed it to this:
| Code: |
| $pre[$i++] = '<pre class="bb-code-block brush:zscript;">'. $code_tag[1] .'</pre>'; |
Same change made to the line just below this in the file. Change the "brush" argument to whatever default highlighting you want for your BBcode tags. In this case I have created my own "brush" for zscript with some simple highlighting rules.
Conclusion
To see an example of this in action on the new web site, go here: http://www.tessh.com/topics/using-syntax-highlighting-posts
Took a while to get this all figured out and working. Hopefully this will help other people trying to integrate syntax highlighting and code posting using CKeditor and Drupal. |
|
|
|
|
Tech
GURU
Joined: 18 Oct 2000
Posts: 2733
Location: Atlanta, USA
|
Posted: Mon Nov 01, 2010 4:23 am
|
I just took a look at those posts and it looks pretty sweet.
|
|
_________________
Asati di tempari! |
 |
|
|
christinecccc
Newbie
Joined: 27 Jan 2011
Posts: 1
Location: Silver Spring, MD
|
Posted: Thu Jan 27, 2011 1:29 am
|
Nice post buddy :)
|
|
|
|
|
|
|
|
|
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
|
|
