My Latest Learn-By-Doing Project: A Vue.js Application Using Firebase Cloud Firestore

A few weeks ago, I decided to take my very basic knowledge of Vue.js and apply it towards learning to do basic operations against a Firebase Cloud Firestore NoSQL database. The result of that project can be found on GitHub at https://github.com/bcswartz/fcf-vue-users. It’s a web application that allows you to create and authenticate user accounts and documents via Firebase's email/password-based authentication API and the Cloud Firestore document and document collection API.

Credit where credit is due: many of the techniques used in the app were borrowed from a very well-written post about using Vue.js with Firestore - https://savvyapps.com/blog/definitive-guide-building-web-app-vuejs-firebase. My project would have taken a lot longer to develop without the information and example code in that post.

Writing the app gave me some basic experience with popular Vue.js tools: the Vue Router, the Vuex data store, and the Vue CLI. Even though it’s a small application, it includes two reusable components - an error message display and a reauthentication modal - and contains an example of using Vue's event broadcasting system.

That reauthentication modal component wasn’t part of my original design plan. While the Cloud Firestore API calls for retrieving and managing documents and documents collections are pretty straightforward, the authentication API calls for performing operations related to user accounts only work if you have a fresh set of credentials (in this case, email address and password) for the user account you want to modify.

That can be quite a restriction. The reauthentication modal allows the current user to update their own email address and password even if their authentication session has grown stale, but I didn’t see any way for the current user to make email/password changes to another user’s account. So that’s something to keep in mind if you want user management features in your application.

Anyway, if you’re interested in getting your feet wet with Vue.js, or Firebase, or both, and are looking for a sample application, check out the repo. More details about what’s in the application can be found in the README file and in the src/views/Notes.vue file within the app.

Instructing Proxyquire To Ignore Nested Requires

When writing unit tests for Node.js applications, you can use the proxyquire npm module to override the modules pulled in by the file under test using require(), replacing them with your own.  So say your file containing the methods you want to test pulls in two other modules using require:

//underTest.js
var moduleA = require( './moduleA' );
var master = require( '../../core/master' );
...
module.exports = {
  runFoo: function() { return moduleA.outputResult() }
};

...in your unit test, you can use a stub library like Sinon in conjunction with proxyquire to instantiate the file under test but with the stubs used in place of the normal modules:

//underTest.spec.js
var sinon = require( 'sinon' );
var proxyquire = require( 'proxyquire' );

describe( 'underTest.js functions', function() {
  var stubModuleA, stubMaster;

  before( function() {

    var stubModuleA = sinon.stub();
    var stubMaster = sinon.stub();

    underTest = proxyquire( './underTest', {
      './moduleA': stubModuleA,
      '../../core/master': stubMaster
    });
  
  });
  
});

...and then you can spy on and define the function behavior of the stubbed objects for your tests.

When I first did this, I ran into problems because one of the modules I was replacing (say moduleA) itself pulled in a module of its own:

//moduleA.js
var main = require( '../../main' );

...and in that main module were functions that executed as soon as the file was loaded via require(), and the execution of those functions caused the before() block of my test file to bomb.

After some research, I discovered that one solution was to use proxyquire to override the require() call in moduleA, and instruct proxyquire to essentially ignore the require by not calling through to it.

//underTest.spec.js (revised)
var sinon = require( 'sinon' );
var proxyquire = require( 'proxyquire' );

describe( 'underTest.js functions', function() {
  var stubModuleA, stubMaster;

  before( function() {

    var stubModuleA = proxyquire( './moduleA', {
      '../../main': { '@noCallThru': true }
    });
    
    var stubMaster = sinon.stub();

    underTest = proxyquire( './underTest', {
      './moduleA': stubModuleA,
      '../../core/master': stubMaster
    });
  
  });
  
});

Introducing Sparker: A Codebase Library Management Tool Showcasing AngularJS, Protractor, and Grunt Techniques

Sometimes projects take on a life of their own, and you end up with something unexpected.

I set out to create an template for CRUD-focused single page AngularJS web applications, something I and perhaps my colleagues could use as a foundation for writing new applications.  But under the momentum of self-applied scope creep, what I ended up creating was a Grunt-powered codebase library management tool, with my original template concept as the first codebase of potentially multiple foundational codebases.

After sitting back and looking at what I ended up with, I decided to name the project Sparker for two reasons:

• I didn't want to use terms like "templates", "scaffolds", or "foundations" for the codebases housed in the project (partly because the project encourages creating demo codebases to accompany the "clean slate" template codebases).  So the codebases are organized into "sparks" and Sparker is the tool for managing them.

• I wanted to focus on the inspirational aspect of the project:  that, at worst, the techniques in the sparks and in Sparker could "spark" ideas in other developers for how to approach certain problems.

At the end of the day, I see Sparker as a functional proof-of-concept, something individuals or particular teams can play around with or use in their shops to maintain and build off of their own spark libraries, but not something adopted for widespread use by the developer community.  It's not designed to compete with things like Yeoman or Express.js because, like I said, it didn't come out of a design.  But it was fun to develop, and I think there's value in sharing it.

Some of the things you'll find in Sparker today:

• An example of how to organize Grunt tasks and task options into separate files, and how to execute two different sets of tasks from the same directory/Gruntfile.

• A Grunt build task that determines which resource files to concatenate based on the <link> and <script> tags in your index.html file.

• A technique for executing the login process and running certain sets of Protractor tests based on the user role being tested.

• Convention-based Angular routes for restricting user access based on authentication state/user roles.

• Example of mocking REST calls within a demo Angular application using the ngMockE2E module.

• Examples of Angular unit tests and Protractor tests that utilize page objects.

Sparker is available on GitHub at https://github.com/bcswartz/Sparker.

Task-based web browsing: Grunt and the grunt-open plugin

Lately I've been playing around with Grunt, which is a JavaScript-based task runner similar to Ant and Gradle. Generally, these tools are used to automate software builds, but they can be utilized in other ways.

While browsing through the large collection of Grunt plugins, I came across one called grunt-open. The grunt-open plugin lets you create a task that opens a URL in your web browser. It looks like it was created with the idea of opening a web page at the end of a chain of Grunt tasks to check the result of a software build. But I thought it might be useful in automating everyday web browsing tasks.

I like to start off my work day with a bit of Internet humor and I have certains sites I visit for that. Dilbert has a new strip every day, while JoyOfTech and XKCD get published every Monday, Wednesday, and Friday, and the XKCD "What-If" article is published once a week, usually by Thursday. Rather than manually opening the appropriate bookmarks for the appropriate day of the week, I figured I'd program a task to take care of opening the appropriate sites.

I won't reinvent the wheel here trying to explain the basics of Grunt: the Grunt "Getting Started" guide does a good job of explaining how to install Grunt and generate the files needed (the package.json and the Gruntfile.js files). Here's what my Gruntfile looks like:

So in the directory where this Gruntfile.js lives, I just have to type "grunt webhumor' in the command, and Grunt will open the appropriate sites. Not a huge timesaver, but kinda cool.

Quick AngularJS Tip: Relating User Input Data to Metadata

I started learning AngularJS a few weeks back because I thought it would work well for an internal tool I was building (more on that in a later post).

Many AngularJS examples, including those in the current AngularJS tutorial (like this one), illustrate how to use the ng-repeat and ng-options directives using a typical Javascript array of objects.  So given such an array in the model:

$scope.plans= [
  {"name": "Basic", "cost": "$250.00"},
  {"name": "Deluxe","cost": "$325.00"},
  {"name": "Premium","cost": "$335.00"}    	
];

...you can output a list of the data like so:

<ul ng-repeat="plan in plans">
  <li>
    {{plan.name}}: {{plan.cost}}
  </li>
</ul>

But, as noted in the AngularJS API, you can also use ng-repeat and ng-options to loop through a set of properties/keys in an object, and that works even if each property references another object.  So you can accomplish the same thing with this model object:

$scope.plans= {
  "Basic": {"cost": "$250.00"},
  "Deluxe": {"cost":"$325.00"},
  "Premium": {"cost": "$335.00"}    	
};

...and this HTML:

<ul ng-repeat="(planKey,planObject) in plans">
  <li>
    {{planKey}}: {{planObject.cost}}
  </li>
</ul>

The advantage to using the latter technique comes into play when you want to relate something in the part of the model you want to preserve / process with a part of the model that provides metadata.

Taking the above examples a step further, say you wanted to create a short conference registration form. The user has to select a conference package, and you want to provide information about each package (what it entails and the cost) but you don't want that information to be part of the form submission. You can do this by having the user's conference selection pull the related data from the plan metadata.

So with the following AngularJS controller function:

function ConfReg($scope, $http) {
  $scope.reg= {};
  $scope.reg.plan= "Basic";
  
  $scope.plans= {
    "Basic": {
      "description": "Access to all first-run conference sessions on Thursday and Friday.",
      "cost": "$250.00"
    },
    "Deluxe": {
      "description": "Access to all first-run conference sessions on Thursday and Friday, access to repeat sessions on Saturday.  Complimentary breakfast included all three days.",
      "cost": "$325.00"
    },
    "Premium": {
      "description": "Access to all first-run conference sessions on Thursday and Friday, access to repeat sessions on Saturday.  Complimentary breakfast included all three days.  Also includes conference t-shirt and kazoo.",
      "cost": "$335.00"
    }

  };
}

...and the corresponding HTML:

<h3>Conference Registration</h3>
  <form name="regForm" id="regForm" ng-controller="ConfReg">
    <p>
      <label>First Name:</label>
      <input type="text" name="firstName" id="firstName" ng-model="reg.firstName" />
    </p>
			
    <p>
      <label class="control-label" for="lastName" id="lblLastName">Last Name:</label>   
      <input type="text" name="lastName" id="lastName" ng-model="reg.lastName" />
    </p>
				
    <p>
      <label class="control-label" for="plan" id="lblPlan">Conference plan:</label>   
      <select name="plan" id="plan" ng-model="reg.plan" ng-options="planName as planName for (planName,planObject) in plans"></select>
    </p>
    <div>
      <p>{{plans[reg.plan].description}}</p>
      <strong>Price:</strong> {{plans[reg.plan].cost}}
    </div>
				
</form>

...The user's selection of plan determines which plan object data is pulled from the "plans" part of the model for display in that div block, yet the data sent as the form submission (the "reg" object) only includes the plan name.

Overcoming the Cookie Size Limit When Using jQuery DataTables and Saved State

One of the features of the jQuery DataTables plugin is that you can use the configuration option "bStateSave" to store the current view of the table (the sort order, the number of rows displayed, the filter term, etc.) in a cookie, so if the user navigates away from the page then comes back, the table view is the same as how they left it.

However, if your website or web application stores the state of several DataTables, and a user hits all those tables faster than those cookies can expire (their default lifespan is 2 hours but can be customized with the "iCookieDuration" option), the user could hit the browser cookie size limit and start seeing errors on your site.  I ran into this problem today with an application I've been working on.

Fortunately, starting with version 1.9, DataTables provides functions that let developers intercept the process of saving the table state and reloading that state, and the plugin author provides a documentation page on how to use those functions to store the state data in localStorage, which in most browsers allows you to store a few MBs of data per site (far more than the 4K limit per site for cookies):

http://datatables.net/blog/localStorage_for_state_saving

In my case, I decided that I would store the state data in sessionStorage rather than localStorage, but the principle was the same.

dirtyFields jQuery Plugin Updated with New Options/Functions

I've made some updates to my dirtyFields jQuery plugin.  Here's the rundown:

• Added two new public functions:
  • getDirtyFieldNames() returns an array of all currently dirty fields.
  • updateFormState() checks the clean/dirty state of all form fields in the specified container
• Made two changes to how the CSS class denoting a dirty/changed form is applied:
  • Added a new configuration option ("self") to apply the class to the actual form element.
  • Split the single option for applying a style to a changed text input and select drop-down into two separate options for granular control (if you used the textboxSelectContext option with a previous version of the plugin, you will need to update your code).
• Added three new configuration options to control plugin behavior:
  • The denoteDirtyFields option controls whether or not the dirty CSS class is applied to the form elements that are dirty/changed.
  • The exclusionClass option specifies the name of the CSS class that, when applied to a form field, will exclude that field from being processed by the plugin.
  • The ignoreCaseClass option specifies the name of the CSS class that, when applied to a form field, will instruct the plugin to do a case-insensitive evaluation of the current and original states of the field.

All of these changes were implemented in response to code suggestions made a team of developers (listed in the GitHub readme.txt file) who modified the plugin to meet their specific needs in one of their intranet sites.

Adding a Time Selector to the jQuery UI Datepicker Widget

One of the functional requirements for the voter registration application I blogged about recently was that the application should not allow further registrations between the registration deadline (October 16 at 9pm) and a date after the election specified by the state Board of Elections.  For the initial run of the application, I simply hard-coded the deadline and restart date into the application logic, knowing full well I couldn't leave it that way unless I wanted to personally change the code year after year....which I don't.

So this week I set out to write a tool within the administrative interface of the application that would allow a non-programmer to update the deadline and restart date every year.  The jQuery UI Datepicker widget is my tool of choice when it comes to having users enter or edit a date, but I've used a few different approaches to having users enter a time of day.  This time around, I decided to see I if could find something comparable to the Datepicker widget for setting the time.

What I found was a rather sweet plugin called the Timepicker Addon that adds a set of time controls to the jQuery UI Datepicker.  If you customize your jQuery UI download to include both the Slider and Datepicker widgets, you can present the time controls as sliders, like so (without the Slider widget, you get select boxes):

The plugin comes with a number of configuration settings so you can do things like adjust the time increments, change how the time is displayed, and allow the user to denote the time zone associated with the time value.  Once I had the plugin configured the way I wanted, I simply had to write some code to validate the date and time string submitted from the form field, and I was done.  Very cool.

Tip on Combining Column Filtering and Column Hiding with jQuery DataTables Plugin

I'm a big fan of the jQuery plugin DataTables.  I use it in a number of projects to enhance HTML tables, making them sortable and searchable.

DataTables provides a number of advanced options and functions that let you customize the table's functionality.  One of these functions is fnFilter(), which you can use to filter the table contents based on the presence of a value in a particular column.  The most common use case for this function is to add text inputs to the header or footer of each column, and bind the use of the function to the keyup event, as in the official DataTables example:

$("tfoot input").keyup( function () {
    /* Filter on the column (the index) of this element */
    oTable.fnFilter( this.value, $("tfoot input").index(this) );
} );

 

...The "oTable" is a reference to the DataTables-enhanced table, the first parameter is the value of the input box in the footer, and the second parameter is the index value (position) of the column in the table.

DataTables also provides the fnSetColumnVis() function for showing/hiding columns, which is helpful if you have a table with a lot of columns and want to let the user get rid of the columns they don't need at that moment.  It takes two parameters, the index position of the column you want to hide and true or false to set the visibility state of the column:

oTable.fnSetColumnVis( 1, false );

 

Both are very useful functions, but you have to be careful when you enable both column filtering and column hiding on a single table. Hiding a column takes it out of the DOM, and therefore it changes the index position of every column to the right of the hidden one. While that makes sense, the problem is that DataTables keeps internal track of the original DOM positions and will execute the filter against the column with that original index value.

So say you have a table with columns A, B, and C going left to right.  DOM index positions start with 0, so column A's position is 0, column B's is 1, etc..  If you hide column A, then column B now has index position 0 and column C has position 1.  When you try and filter column C, fnFilter gets the current position of column C (1) and runs the filter against the column that originally had index position 1...which is column B.  So the table gets filtered based on column B even though the user entered their filter term in the footer of column C, which is obviously not what you want.

You can work around this issue by recording the initial index position of each column in an attribute in the input tag, and use that value as the second parameter for fnFilter().  So if you used an attribute like "colPos":

...
    <tfoot>
        <tr>
            <th><input type="text" value=" colPos="0"/></th>
            <th><input type="text" value=" colPos="1"/></th>
            ...
         </tr>
    </tfoot>
...

 

...then you'd rewrite your keyup bind function like so:

$("tfoot input").keyup( function () {
    /* Filter on the column (the index) of this element */
    oTable.fnFilter( this.value, $(this).attr("colPos") );
} );

 

That will keep the column filters tied to their original columns.

Simple Technique For Creating Multiple Twitter Bootstrap Popovers

One of the JavaScript/jQuery plugins that comes with Twitter Bootstrap is the Popover plugin, which lets you create windows of content that appear when you hover over or focus on a DOM element.  They behave like tool tips but are larger and better suited to support styled content.

As noted in the documentation, the title and content of an individual popover can be coded in one of three ways:  via HTML attributes within the DOM element that triggers the popover, by assiging text values to the title and content properties when applying popover functionality to the DOM element, or by assigning functions that return markup to those title and content properties.  Here's an example of the last of those options:

$("#pop1".popover(
    {
        title: getPopTitle(),
        content: getPopContent()
    }
);

function getPopTitle() {
    return "Title 1";
};
		
function getPopContent() {
    return "Content 1";
}

The page I was working on needed to have several popovers, and the popover content included styled text: paragraphs, bolded text, etc. I didn't want to have to put that content into HTML attributes or long string values, nor did I want to code several different invocations of the popover function.

So what I decided to do was to create hidden blocks of HTML to hold the popover content and associate each set of "content" (title and content) with a unique id:

<style>
    .popSourceBlock {
        display:none;
    }
</style>

<div id="pop1_content" class="popSourceBlock">
    <div class="popTitle">
        Title 1
    </div>
    <div class="popContent">
        <p>This is the content for the <strong>first</strong> popover.</p>
    </div>
</div>

<div id="pop2_content" class="popSourceBlock">
    <div class="popTitle">
        Title 2
    </div>
    <div class="popContent">
        <p>This is the content for the <strong>second</strong> popover.</p>
    </div>
</div>

Then I assigned ids to the DOM objects that would trigger the popups when hovered over and gave them a CSS class of "pop". I opted to use one of the icons provide by Bootstrap to trigger the various popovers:

<i id="pop1" class="icon-question-sign pop"></i>
...
<i id="pop2" class="icon-question-sign pop"></i>

Finally, I used jQuery's each() function to loop through all the DOM elements with a class of "pop", grab the id value and use that to locate the matching content to associate with each popover:

$(".pop").each(function() {
    var $pElem= $(this);
    $pElem.popover(
        {
          title: getPopTitle($pElem.attr("id")),
          content: getPopContent($pElem.attr("id"))
        }
    );
});
				
function getPopTitle(target) {
    return $("#" + target + "_content > div.popTitle").html();
};
		
function getPopContent(target) {
    return $("#" + target + "_content > div.popContent").html();
};

With this code in place, I can add new popovers by creating additional hidden HTML blocks and DOM elements with the "pop" CSS class and an id that follows the pattern I've established.

Another nice aspect to this is that, down the road, I could put the page with the HTML blocks in a directory where a web designer or even a client with some basic HTML skills could edit the content, and I could call that file into my page programmatically. So long as they didn't add new content blocks, they could tweak the wording of the content without having to call me to do it (assuming I can trust them not to mess up the HTML formatting).

dirtyFields jQuery Plugin Updated To Fix jQuery 1.6 Compatibility Issue

A few days ago, I received an e-mail informing me that there was a bug in my dirtyFields jQuery plugin having to do with the plugin's evaluation of checkbox and radio button state (the plugin lets you track the state of form elements and highlight changes).

At first, I didn't see the problem and didn't understand the need for the code suggestion he provided because the demo file included in the plugin download worked just fine.  But then I realized that the demo was coded to use an older version of jQuery (the plugin is over 2 years old now), and once I updated the demo to use jQuery 1.7 I could see the problem.

I had coded the plugin to use the jQuery attr() function to check the selection state of checkboxes, radio buttons, and the option elements in <select> elements.  Prior to jQuery 1.6, code like myCheckbox.attr("checked") would return a Boolean value based on whether the checkbox was currently checked or not.  But that changed in jQuery 1.6: now (in 1.6 and higher), myCheckbox.attr("checked") only returns the initial value of the "checked" attribute of the element ("checked" rather than "true"), and returns undefined if the checkbox/radio button element does not possess the checked attribute at all.  The same hold true for the "selected" attribute of option elements.  In jQuery 1.6 and higher, the new prop() function is designed to return the current state of the selected attribute (this change to jQuery is in fact described on the API page for prop()).

So I updated the plugin to use the is() function in conjunction with the ":checked" and ":selected" selectors to evaluate checkbox, radio button, and option state, since that method works with both older and newer versions of jQuery.  The new version of the plugin is available via the GitHub link from its dedicated GitHub Pages site.

Things To Know About Creating Multiple jQuery UI Datepicker Widgets on the Fly

The first time I created a UI where users could create new jQuery UI Datepicker widgets on the web page as needed, I thought about blogging about some of the "gotchas" I ran into trying to do that, but never got around to it.

But after today, when I had to relearn those lessons, I figured I should write something down.  :)

Here's what I've observed about creating new (multiple) Datepicker widgets on the fly:

• Cloning a text field that already has the Datepicker applied to it won't work.  You're better off either cloning a "plain" text input element (<input type="text">) or creating one from scratch when you need it.

• If there's any chance that you're going to end up with multiple Datepicker widgets on the page, you need to make sure that each Datepicker-powered text element ends up with a unique value in the "id" attribute.  Otherwise, the user will click on a date on the pop-up calendar for the most recently-added Datepicker widget, but it'll change the text box value of the first Datepicker widget you added!

  One way to address this is to add a global numeric variable at the top of your Javascript block, increment it every time you want to add a new Datepicker, and combine the current value of that variable with some text and assign that as the id of the text element you're about to add as a Datepicker.

• Do not invoke the datepicker() function (the function that turns the text field into a Datepicker widget) on the new text input element until after it has been added to the page:  clone or create your text input first, place it in the page using prepend(), append(), whatever, and then invoke the datepicker() function on it.

• If you need to remove one of the Datepicker widgets, use the datepicker("destroy") method on it.

Small Update to My jQuery textCounting Plugin

I suspect there aren't too many users of my textCounting jQuery plugin, but if you do happen to use it, I wanted to point out a small update I made to it today.

Previously, the plugin was configured by default to look for the letter or word limit for your textarea control in an attribute called "maxLength."  That used to be a safe attribute name because browsers did not enforce the maxlength attribute on textrareas, only single-line text inputs.  But that's no longer the case with Safari:  if you put a maxlength attribute value of "100" on a textarea, Safari will prevent a user from entering more than 100 characters in that textarea.

So I changed the default attribute setting in the plugin to "maxTextLength" to avoid this issue.  To avoid this issue with Safari, you can either download the updated plugin files, or simply use the settings option in the previous version of the plugin to change the attribute name used by the plugin on a case-by-case basis.  In either case, you'll have to make sure you use "maxTextLength" instead of "maxLength" as an attribute in your textareas.

Adding a Date Range Filter to a Master Table with the dataTables jQuery Plugin

This past week I was asked to build a simple suggestion box web app.  The people responsible for reviewing the suggestions wanted to be able to filter the suggestions by keyword and by date range.

Having used the dataTables jQuery plugin in previous projects, I knew that it could take care of the keyword filtering requirement, but I had never used it to filter out rows that didn't fall into a date range.

I did some research and found enough information to get it working, but since I didn't come across any single crystal-clear example or demo for it, I figured I'd throw one together to illustrate it.  You can check the source code to see what's going on under the hood. I also used the jQuery UI Datepicker plugin to make the date range boxes more user-friendly.  Here's the URL:

https://bcswartz.github.io/jQuery-dataTables-dateRange-demo/

Custom jQuery Validate Rule For Making Sure One Date is Later Than Another

In addition to providing a number of standard validation rules, the jQuery Validation plugin also allows you to create your own validation rules via the addMethod() function.  Today I had a situation where I had to use that function:  I had to create a rule to ensure that the end date of a date range determined by the user was later than the starting date.  I thought I'd share what I came up with.

The details of the situation:

• The user set the starting date using two radio buttons and a text field bound to the jQuery UI Datepicker.  Selecting the first radio button meant that the start date (the "now" button) should be set to the current date, while selecting the second radio button (the "later" button) meant that the starting date would be determined by the value in the Datepicker field.
• The user set the ending date using another Datepicker-bound text field.
• The Datepicker plugin ensures that the date is always in the format "mm/dd/yyyy".

Here is the code:

 

So if the user selected the second start date option and chose a date using the Datepicker widget, the code splits up the date string into an array and uses the individual month, day, and year values to create a Date object. If the user selects the option of making today the starting date, a new Date object is created (which by default has the value of the current date and time) and the code creates a new Date object with the same date but with the time-specific data stripped out (because the end date will not have a time value attached to it).

The Date object for the end date is created with the same technique used for the second start date option, and then the getTime() function is used on both the start and end Date objects to get the number of milliseconds between each date and January 1, 1970 (a starting point for date and time values used in both JavaScript and Java). Then it does the comparison between the two dates.

It's then a simple matter of applying this custom method somewhere within the normal jQuery Validation rules block:

...
rules: {
    endDate: {
      required: true,
      dateComparison: true
    }
...

How to Use the jQuery dirtyFields Plugin with FCKEditor

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 &lt;iframe&gt; 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.

Revision, Re-Release of My dirtyFields jQuery Plugin

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:

https://bcswartz.github.io/dirtyFields-jQuery-Plugin/

Quick Tip: Accessing the Contents of a FCKEditor Box

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.

New jQuery Plugin dirtyFields: Bring Attention to Changed/Unsaved Fields

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.

It applies a CSS class to a contextual DOM element associated with any form field that has been changed from its original value. For text inputs, <textarea>, and <select> elements, the <label> element associated with the field (via the "for" attribute) will be styled with the class. For <checkbox> and <radio> elements, you can specify the text associated with each element using "checkboxRadioTextTarget" plugin option (the default setting is "next span").

It works by storing the current value or state of each form field within the data store of the field using the jQuery data() function.  As the value or state of the form field is changed, its current value/state is compared to the one within its data store, and if they aren't equal the field is considered "dirty".  The plugin includes a function called "resetForm" that can be used after the form has been submitted to update the data store of each field with the new field value and mark all the form fields as clean.  There is also an option to apply a CSS class to the form itself to indicate whether or not it contains dirty fields.

(UPDATE: I've now added support for a "formIsDirty" callback function that can be used in conjunction with the "denoteFormDirty" option to run your own functions once a form has been determined to be clean or dirty.)

Links to a demo and documentation can be found below the following screenshot, which shows the style changes to the labels and text of form elements that have been changed:

Project homepage: https://bcswartz.github.io/dirtyFields-jQuery-Plugin/

The Risk of Performing JavaScript Operations Around User-Generated HTML

Last year I wrote a ColdFusion application that included a page where an editor could take a list of short news abstracts and manipulate them (reorder them, place them in categories, add divider lines, create anchor links to highlighted stories, etc.) using a number of jQuery-powered JavaScript functions. It gives them a lot of control over the final layout, and they're pretty happy about it.

However, there have been occasions when this layout tool doesn't work at all. Why? Unclosed HTML tags in the abstract data.

The page they use to enter the news abstracts is comprised of several plain HTML text fields, a set of category checkboxes and two WYSIWYG textarea boxes (powered by JavaScript) for the abstract itself. I gave them the WYSIWYG boxes because I knew they would want to be able to do some basic HTML formatting on the abstract text (boldface, italics, etc.), and the WYSIWYG editors do produce solid, clean HTML.

What they do that gets them in trouble is they enter HTML tags (usually for italics) into the title form field, which is a normal HTML text field. Every once in awhile, they forget the closing tag or maybe just an angle bracket...the abstract itself saves correctly but when they get to the layout tool, that unclosed HTML tag messes up the entire DOM structure the layout tool is programmed to manipulate, rendering it non-functional.

They've now learned that when the header text of the various layout tools appears in italics, that usually means they've got an unclosed italics tag that needs fixing. It's easy enough to fix once they figure out which news item is responsible.

So a word of warning: if your JavaScript functions are designed to act upon HTML code that you yourself don't have complete control over (or the ability to make sure the HTML is clean and proper), consider the possibility that your JavaScript may end up breaking due to the content.