Thought Delimited

A commenter named Dean recently asked me if there was a way to use an FCKEditor field with my dirtyFields jQuery plugin.

When applied to a form or any container that contains HTML form elements, the dirtyFields plugin records the intial values or states of each form element, and then anytime the change event is triggered on any of those fields, the plugin functions compares the current value or state of the field to the recorded value/state and then applies certain CSS styles to certain page elements (as defined by the user) if that particular field has been changed.

There are two problems with trying to use an FCKEditor element with dirtyFields. The first is that the FCKEditor Javascript generates the page elements it uses to represent the editor window after the page has been loaded, after the jQuery document.ready event typically used when binding plugin functions and events to page elements. The second problem is that the editor content window (where the user does their typing) is contained in an <iframe> element, and as such the text within the editor window and any events triggered within that window aren't accessible to the dirtyFields plugin.

However, it is possible to get a handle on what's going on within the editor window by utilizing the FCKEditor API and then use some of the public functions within the dirtyFields plugin to make it work.

First the code, then the explanation:

<script type="text/javascript">
    function FCKeditor_OnComplete( editorInstance )
        {
            editorInstance.Events.AttachEvent( 'OnBlur' , checkForChanges ) ;
            $.fn.dirtyFields.setStartingTextValue($("#editorField"),$("#myForm"));
        }
			
    function checkForChanges( editorInstance )
        {
            $("#editorField").val(editorInstance.GetXHTML(true));
            $.fn.dirtyFields.updateTextState($("#editorField"),$("#myForm"));
        }
	
    $(document).ready(function() { 
	$("#myForm").dirtyFields();
       ...whatever other functions you want to run...
    });
</script>

<form name="myForm" id="myForm" method="post" action="something.cfm">
    <label id="lbl_editorField" for="editorField">FCKEditor Window:</label>
    <cfmodule
        template="/fckeditor/fckeditor.cfm"
        basePath="/fckeditor"
        instanceName="editorField"
        value=''
        width="600px"
        height="200px"
    >
    ...
</form>

A note about how I'm using FCKEditor in this example: the example is based off of a ColdFusion page I wrote in order to try this out, so I used the <cfmodule> tag to create the FCKEditor field. Programmers using version 8 or higher of ColdFusion can instantiate an FCKEditor field using the <cftextarea> tag, but I suspect the FCKEditor API calls will work the same in either case. 

As I said earlier, one of the problems was that the HTML elements created by FCKEditor were created after the page loaded. The FCKeditor_OnComplete() function solves this problem: it executes as soon as FCKEditor has finished creating the HTML elements needed to support the editor, and provides the instance of the editor as an object ("editorInstance" is simply the name assigned to the object in the FCKEditor API examples, so I followed their lead). One of the elements it creates is a hidden text field with an "id" attribute equal to the name of the FCKEditor instance. My example presupposes that the FCKEditor field in the form is named "editorField", in which case a hidden text field with an id of "editorField" now exists in the form.

The first line in the FCKEditor_OnComplete function binds the checkForChanges() function to the editor's "OnBlur" event, which means that any time the user navigates away from the editor window (either by pressing the Tab key or clicking on another page element with the cursor), the checkForChanges() event will fire (Note: for a while, I was convinced the API didn't provide a way of detecting a loss of focus because "OnBlur" isn't documented on the API page). The second line uses the dirtyFields setStartingTextValue() public function to record and save the value currently contained with the "editorField" hidden text field, so that dirtyFields has an initial value to compare any changes in the editor window against.

The checkForChanges() function also receives an instance of the editor as an object. The first line in the function uses the getXHTML() method of the editor object to retrieve the current contents of the editor window and copy it into the value of the "editorField" hidden text field. The second line calls the updateTextState() function of dirtyFields, which tells dirtyFields to compare the current value of the "editorField" hidden text field with the previous value recorded by the setStartingTextValue() function. If the values are different, the label associated with the "editorField" hidden text field will be styled to indicate that the content of the FCKEditor window is "dirty."

And that's all there is to it: even though the dirtyFields plugin can't interact with FCKEditor fields by default, the public functions provided by the plugin can be used in conjunction with the FCKEditor API to make it work.

I was pretty happy with the functionality of my original dirtyFields jQuery plugin, but as comments and questions about the plugin started coming in, I soon realized that there was a lot of room for improvement.  So I spent the last few weeks reworking the code to create a more flexible, more powerful version, one that completely replaces the original version.

The main purpose of the plugin remains the same:  it helps you show a user exactly which HTML form fields have been changed (made "dirty") since the page was last loaded or saved (text inputs, drop-downs, checkboxes, etc.).  But the new version of the plugin gives you more control over what page elements are affected when a particular form field is changed, provides callbacks that let you execute your own functions before and after a form field is processed by the plugin, and includes over a dozen public functions for manipulating individual form fields or the entire form (including functions that let you add the plugin event handler to any new form fields you add to the form dynamically after the page is loaded).

I created a website to go along with the new plugin that provides full documentation on all of the plugin settings, callbacks, and public functions and three working examples that demonstrate the plugin in action.  You can go there to learn all of the details:

http://www.thoughtdelimited.org/dirtyFields/index.cfm

Today I found myself needing a way to access the current contents of a FCKEditor instance on a web page via Javascript (I needed to create a "preview" dialog box that would show the user what the content would look like when published).  After some searching on Google, I learned that by instantiating FCKEditor on the page, I had access to the FCKEditor API and could access the content with the following statement:

var editorContent = FCKeditorAPI.GetInstance("postText").GetXHTML(true);

...where "postText" is the id value ("instanceName") of the editor.

Usually, finding a particular value in a Javascript array requires looping through the array until you find the value you're looking for.

jQuery provides a utility function called inArray() that takes the value being sought and the array as parameters and returns the index value indicating where in the array the value is located (-1 is returned if the value is not found in the array):

var index= jQuery.inArray(theValue, theArray);

You can use this jQuery function in conjunction with the Javascript push() and slice() functions to easily add or remove a value from an array:

//If you're not using any other Javascript library that utilizes the $ sign, you can use the $ sign 
//instead of the jQuery namespace
var index= $.inArray(theValue, theArray);
if(index== -1)
   {
     //Value not found in the array.  Add to the end of the array with push();
     theArray.push(theValue);
   }
else
   {
     //Remove from the array using splice(). Splice takes the index value of where you want to start 
     //removing items from the array as the first parameter, and then the number of item you want 
     //to remove as the second parameter.
     theArray.splice(index,1);
   }

I just finished a project that included an administrative page where users could make changes to a parent record and numerous child records via multiple forms. All of the form submissions were done via AJAX, so I needed a way to illustrate which of the forms on the page contained changed or "dirty" data, and which forms had no unsaved changes.

This dirtyFields plugin is derived from the functions I wrote to handle that task in that project.

Read more...