software, bourbon, and the banjo

CKEditor is a wonderful rich text editor written in Javascript. It more or less replaces a textarea with a robust WYSIWYG editor. Integrating it into your Mach-II application is extremely easy with the new Form taglib and HtmlHelperProperty. This article assumes you’ve already downloaded, extracted, and copied the CKEditor files into whichever directory you keep your Javascript files in.

First thing’s first: you’ll need to declare the HtmlHelperProperty in your mach-ii.xml file. In my case, the directory where I keep all my Javascript files is in the project directory, so I need to modify the jsBasePath parameter; the default will look in the absolute-referenced /js directory:

    <property name="html" type="MachII.properties.HtmlHelperProperty">
      <parameters>
	<parameter name="jsBasePath" value="js"/>
      </parameters>
    </property>

Once that’s in place, your application will be able to use all the cool functionality introduced with the HtmlHelperProperty. To learn more about this property, check out the specification on the Mach-II wiki.

The next step will be to make the form aware of the new Form taglib. This is easily accomplished by adding the following line to the top of your cfm file:

<cfimport prefix="form" taglib="/MachII/customtags/form" />

Again, feel free to refer to the documentation to learn more about the Form taglib.

Since we plan on using the CKEditor, we should probably import that Javascript file. I assume that most people use a templating scheme of some sort, so adding per-page Javascript files can get kind of hairy. Luckily the HtmlHelperProperty we declared earlier makes this extremely easy. Simply add the following line under the Form taglib declaration:

<cfset getProperty("html").addJavascript("jquery-1.3.2.min.js")/>
<cfset getProperty("html").addJavascript("ckeditor_basic.js")/>

I went ahead and threw in the JQuery declaration since we’ll be using that in a few minutes.

Now we need to define a textarea control that we’re going to replace with the CKEditor. In our test file, we’ll call this field description as if we’re describing some product in a bookstore.

  <form:form actionEvent="product.create" bind="product">
    <!--- . . . --->
    <form:textarea path="description" rows="10" cols="50"/>
     <!--- . . . --->
  </form:form>

So far, so good, and so simple. The next step is to actually add the Javascript code that replaces the textarea with the CKEditor control. The documentation suggests that you either do this directly after you create the textarea or put the code in function to be called when the page is finished loading. Fortunately JQuery makes this simple.

<script type="text/javascript">
var onLoadFunction = function() {
  CKEDITOR.replace("product");
};
 
$(document).ready(onLoadFunction);
</script>

All it takes is a couple dozen lines of code and your textarea can support rich text. Wow your friends, neighbors, and bosses, while you secretly let Mach-II do the heavy lifting, a glass of your favorite bourbon in hand. If you don’t like bourbon, I’ll hold your glass for you.

This entry was posted on Thursday, November 12th, 2009 at 11:04 PM and is filed under Mach-II. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.