Simple Implementation of a Protected ObservableArray in KnockoutJS

Recently I worked on an exercise building the UI for a table grid-based app,  where you can click on a row to reveal an edit view that presents the record in more detail.  For the bindings, I utilized knockout.js (note this article assumes some basic understanding of how two-way bindings are implemented using knockout).

table grid
The Table Grid
edit record view
The Edit Record View

As part of the exercise I was aiming for usability. And in line with that, it struck me that if you happen to be in the edit view, edit a number of attributes, and then realize you made mistakes, that you should be able to revert back to the original data. Problem is in knockout.js, the bindings done with Observables and ObservableArrays update your viewmodel immediately, leaving you with no way to revert short of another request to the server.

Google to the rescue.  I found this exemplary Knock Me Out blog post by Ryan Niemeyer on how to handle committing or resetting edits on Observables.  I’m hardly one to be above borrowing code from those more talented than myself, so I incorporated it and found his protectedObservable to work fantastic … at least for attributes that would normally be observables.

But I also had a number of observableArrays, and these are where the rollback functionality is especially needed, as relying on a form reset wouldn’t help us with deleted array elements.  Some more googling and I found this jsFiddle, also by Ryan, and I thought I was golden.  Turned out my joy was premature as it didn’t work for me, though this was through no one’s fault but my own.  If I had read his comments more closely I would have seen it was designed to work only with observableArrays of primitive types.  My observableArrays contained objects which themselves contained observables and observable arrays (which, in turn, contained objects).  So I had, at hand, what I thought was a more complex issue.

But the solution turned out to be quite simple!

Basically, I just made a shallow copy of the initial array that we would keep around for the case we want to rollback, and attached “reset” and “commit” functions to an observableArray to create our “protectedObservableArray,” keeping the same interface that Ryan implemented.  Reset basically works by clearing our observableArray, then iterating through our copy of the array, calling .reset() on any elements that have such a function, and pushing those elements onto the observableArray.  Commit is similar in that you iterate through the elements in the observableArray and call .commit() on the element if the function exists, and then resetting our rollback array to a shallow copy of the array underlying our observableArray.  Easy stuff!

//allow commit/reset functionality on an observableArray
ko.protectedObservableArray = function protectedObservableArray(initialArray) {
  var m_rollbackValue = initialArray.slice(),
      result = ko.observableArray(initialArray);

  //commit result values
  result.commit = function () {
    var x,
        len,
        el;

    for (x = 0, len = result().length; x < len; x += 1) {
      el = result()[x];
      if (el._destroy) {
        el._destroyCommitted = true;
      } else if (typeof el.commit === 'function') {
        el.commit();
      }
    }
    m_rollbackValue = result().slice();
  };

  //reset to rollback values
  result.reset = function () {
    var x,
        len,
        el;

    //clear out underlying array in observable
    result().length = 0;

    for (x = 0, len = m_rollbackValue.length; x < len; x += 1) {
      el = m_rollbackValue[x];
      if (typeof el.reset === 'function') {
        el.reset();
      }
      if (el._destroy && !el_destroyCommitted) {
        el._destroy = false;
      }
      result.push(el);
    }
  };

  return result;
};

But there’s always a “but.”  In this case, this protectedObservableArray works fine if all its members are either protectedObservables or protectedObservableArrays. But what if we want our arrays to contain more complex objects whose members, in turn, could be protectedObservables, protectedObservableArrays, or additional objects?  These objects do not have any reset/commit functionality, and in turn, these objects’ members will not have their reset/commit functionality triggered.  Allowing our arrays to contain members that are not primitives was the whole point of coming up with this protectedObservableArray implementation, in the first place.

One approach would be to iterate through all the members of any object, and if said object has an own property “commit” (or “reset”) that is of type “function”, then call the function.  The issue with this approach is we’re going to end up having to handle nested objects, not to mention having to handle objects we don’t want to check (such as functions), and this code is going to become ugly pretty fast.  (But feel free to take it on, if you so desire).

I took what I think is a more elegant, and easier, approach that involved making available the ability to extend our objects with reset/commit functionality.  .reset() would iterate though the members of the object and call their .reset() functions (if they have one), and like-wise for .commit().  Any nesting of objects becomes irrelevant as our “protected” objects share the reset/commit interface the other protected members have.

The code, encapsulated in a constructor function I added to the ko namespace, ended up like this:


ko.ProtectedObjectExtend = function ProtectedObjectExtend() {
  if (!(this instanceof ko.ProtectedObjectExtend)) {
    return new ko.ProtectedObjectExtend();
  }

  this.commit = function () {
    var prop;
    for (prop in this) {
      if (this.hasOwnProperty(prop) && typeof this[prop].commit === 'function') {
        this[prop].commit();
      }
    }
  };

  this.reset = function () {
    var prop;
    for (prop in this) {
      if (this.hasOwnProperty(prop) && typeof this[prop].reset === 'function') {
        this[prop].reset();
      }
    }
  };
};

Now, for any object type we want to have this functionality we can either set or extend its prototype with an instance of ko.ProtectedObjectExtend, or in the case of an object instance we can extend that instance:

//set prototype of object type
MyClass.prototype = new ko.ProtectedObjectExtend();

//extend prototype of object type
MyClass.prototype = $.extend(MyClass.prototype, new ko.ProtectedObjectExtend());

//extend object instance
myObject = $.extend(myObject, new ko.ProtectedObjectExtend());

The only issue with this approach is our objects cannot have members called reset or commit, else only one version of the member will survive the extend call.  So design your objects with that in mind.

And that will do it. If you go back to the demo I built–http://phhht.com/health–you can see it in action on the edit view. Try clicking “Cancel” to undo any changes, and clicking “Save” to commit changes. (Re-click “edit” to return to the edit view and see if it reset or committed as expected).

I’ll be checking this code into my GitHub in the coming days, but in the meanwhile I would appreciate any feedback or questions.

Advertisements

Responsive Analog Clock with CSS3 and JavaScript

My current place of employment is growing quite rapidly, and as such is doing quite a bit of hiring.  This means I, and others, end up doing quite a bit of interviewing.  One of the questions one of my coworkers asks in interviews involves how analog clocks work.  A few months back, I was thinking about this while doing some reading about CSS3, and naturally the thought of building an analog clock with CSS3 came to mind.

I say naturally as it has evidently come to mind for quite a few people as a useful academic exercise to flex their CSS3 muscles on.  A quick Google search for “css3 analog clock” comes back with a hearty handful of such renderings.  One in particular I like is “CSS3 Analogue Clock without using Images” by Matt Walker, as it renders the clock face solely with HTML5 and CSS3; ie, he uses no images.  It takes an approach similar to how I did, using common digits rather than Roman numerals, and rotating them appropriately with CSS3 transforms.  I particularly like how Matt went beyond the simple clock face and built up the entire clock body with CSS.  Pretty cool stuff!

Aesthetically speaking, my clock is not nearly so fancy.  One of the challenges I did present to myself when building this clock, however, was to make it responsive.  That is,  to use relative measures and have it (re)size itself appropriately to the width of the viewport.  What I’d like to discuss here is the technique I used to make it responsive.  If you want to test its responsiveness, resize your browser.  Or if using a mobile device, rotate it.  The other thing I did differently was utilize requestAnimationFrame to have the second-hand scroll smoothly, as opposed to doing one second ticks/jumps.  I won’t get into that, here (but do feel free to check out the code).

Basically, responsive design involves building an HTML UI utilizing relative CSS measures and appropriate breakpoints, usually defined with media queries, to make the UI resize elements, show/hide elements, and basically structure itself appropriately based on the width of the viewport.  But I’m assuming you’re aware of all that.  If not, Ethan Marcotte’s seminal article on Responsive Web Design can provide you with more details on how it generally works.  (If you check it out, be sure to resize your browser while at the start of the article and watch what happens to the lead image).  Or if you want the nitty-gritty details on responsive design, including handling images and tables, Aquent Gymnasium offers an outstanding free course on the topic.

So let’s get going.  The responsive analog clock can be viewed here: http://phhht.com/putz/clock.html

If you try resizing your browser to a width under 480px you should see the size of the clock shrink in a responsive manner relative to the width of the viewport.  You should also notice it has a maximum width of about 480px when increasing the width of the viewport.

There’s nothing radical with how I implemented it.  Every HTML element that makes up the clock has its size defined in ems, such that the size of the child elements are relative to the size of their parent elements up to the one top level div.  I can then reset the size of the clock by simply setting a single CSS property on the top level div–the font-size–and this changes the size of each child element proportionately.  Some code may make this clearer.

The HTML for the clock is really basic:

<div id="clock">
    <div id="hour"></div>
    <div id="minute"></div>
    <div id="second"></div>
    <div id="center"></div>
</div>

Our top level element is #clock, with four immediate children nested whose purposes are self evident.  I think we can simply focus on #clock and #center to come to understand the technique used.

In the CSS, I set the base font size for the body to 16px (which is generally the default you would get, anyway), and then define the CSS for our elements sizing them using em as our measurement.

html, body {
    font-size: 16px;
}

#clock {
    width: 30em;
    height: 30em;
    border-radius: 50%;
    border: solid 2px black;
    margin: auto;
    position: relative;
}

#clock #center {
    height:2em;
    width: 2em;
    border-radius:50%;
    top:14em;
    left:14em;
}

For #clock, the CSS makes our div round with a diameter of 30em (by setting border-radius to 50%, and the width and height to 30em).  It is important to note that #clock inherits the font-size of 16px from the body, as this means 1em for #clock is, by default, 16px.  As far as the ems for the child elements, we only care that em is a relative measure to em for #clock.  For instance, #center represents the dot at the center of the clock face.  We give #center a diameter of 2em, so we can center it by positioning its “upper left corner” relative to #clock‘s “upper left corner”  14em from the left and 14em from the top.

So what we have at this point is a circle with a diameter of 480px (30em x 16px) that has a black dot in its middle whose diameter is 32px (2em x 16px).  If we make our viewport width less than 480px at this point, our circle and dot sizes don’t change correspondingly.

So let’s say we tried setting the font-size for #clock to 10px.  What we should find is the diameter of our circle is now 300px (30em x 10px), and the dot now has a diameter of 20px (2em x 10px), and is still centered in our circle.  Since #clock is our top level element, by setting font-size to 10px, we have defined the size of an em to 10px for all elements that make up the clock (so long as we don’t specify the font-size of any child elements to a physical measure).  And note that since we defined how we positioned our dot (#center) in ems as well, it remains in the center when we change the font-size of #center.  So changing the size of our clock is as simple as changing the font-size of our top-level element for the clock.

At this point, it should be becoming apparent how we’ll make the clock responsive.  The most obvious way would be to define a media query for a viewport width of 480px and greater that sets the font-size of #clock to 16px, and define other breakpoints at lower viewport widths (less than the width) with correspondingly lower font-sizes for #clock.  And that should work, though you’ll only have the width (diameter) of the clock maximized when the viewport width matches exactly our media queries.

Alternatively, I took an approach of resetting the font-size of #clock with a handler for the window resize event:

function setSize() {
    var b = $("html, body"),
        w = b.width(),
        x = Math.floor(w / 30) - 1,
        px = (x > 15 ? 16 : x) + "px";

    $("#clock").css({"font-size": px });
}

$(document).ready(function () {
    setSize();
    $(window).on("resize", setSize);
});

So now when we resize the browser window to below 480px, we see the size of our clock resizing proportionately for all widths, much like you’d see an image responsively resize when you set the max-width of it.

Now you may be thinking I’ve only demonstrated resizing a circle and a dot proportionately.  Well, the technique demonstrated here will work for all elements that make up the clock so long as you are sure to size and position them with ems.  (Setting the rotation angle with CSS transforms does not need to change as the angles involved don’t change as the size does).  But given that, If you are interested in seeing how I got my analog clock fully built and functioning, the un-minified CSS and JavaScript are here and here.

So there you have it: a technique you can use to build a responsive analog clock with CSS and JavaScript.  Comments?  Thoughts?   Love?  Rage?  Please share.

Book Review: jQuery 2.0 Development Cookbook (PACKT Publishing)

I was recently presented with the opportunity to review the newly published jQuery 2.0 Development Cookbook by Leon Revill (PACKT Publishing, 2014) on Amazon.com.  In exchange, I received the book for free in electronic format from the publisher. Following is my review.

When I choose books to purchase and read, I tend to look at specific topics and the strength of the reviews associated with it. There already is a highly rated jQuery Cookbook available, published over 4 years ago, that is well reviewed. So do we really need another one? And if so, why?

Perhaps the answer is in the title, jQuery 2.0 Development Cookbook; ie, with a focus on 2.0 it is meant to be an up-to-date introduction to the implementation of common patterns addressed by jQuery. So with that context, I read this book also trying to grasp the intended audience—the book claims it is for novice to expert users of jQuery—and does it stay true to modern patterns and widely held best practices. (As a disclaimer, I was given a free copy of the book by the publisher on the promise I would provide a review).

Reading the first chapter, I found the book got off to a rough start. I found the recipes generally simplistic, and the writing to be terse to the point I had to reread some parts to understand what the author intended (as I read on in the book, I found this to be much less of an issue). One recipe in particular bothered me, perhaps more than it should. “Populating list elements” uses jQuery’s each function to iterate over a JSON array and append attributes of each element as a list item to an unordered list in the DOM. DOM manipulations are expensive, and it would have been preferable to see the unordered list built up as a document fragment, and then appended to the DOM so we only make one addition to the document in the recipe. This pattern is repeated in a subsequent recipe “Understanding pagination.”

As I started getting to the middle of the book, I thought the author was really finding his voice. It was called out in recipes to use event delegation (another best practice), though not in those words, as well to use find to select from a current set of matched elements as an optimal practice. The recipes, themselves–such as building a basic photo gallery, drag and drop functionality, accordion content slider, and so on—are useful and it’s good to understand the patterns to build them regardless of whether you use jQuery or not. I do like that the author explicitly called out recipes that could be implemented more simply with jQuery UI. If you simply need one or two of these recipes in your work, it is better to implement these yourself than to take on the bloat associated with jQuery UI. And in reflecting on it I feel this part of the book is where it earns its true value. The cost of the book is likely less than the hourly rate of anyone reading it, and will more than make up its value if you use just one of the recipes.

The latter chapters on jQuery UI and jQuery Mobile serve as basic introductions to the technologies, and may be useful if you have not worked with them before. (In the jQuery Mobile chapter, the recipes on implementing quick call and SMS functionality really are just simple capabilities introduced with HTML5 and are only tangentially related to jQuery mobile).

I would have found more useful, and I really would have liked it, if the author had gone into more advanced patterns that are becoming accepted practices with some of his recipes, in particular promises and jQuery’s deferred object. Also, jQuery 2 allows for customs builds, and an introduction to this as a recipe would have been both timely and topical, in particular since the title of this work indicates this is a recipe book built on jQuery 2.0. I suppose in that sense, the title is misleading. This book could easily have been released three or four years ago and not used jQuery 2.0 with little changed in the book.

So, to summarize. If you are newer to jQuery and the literature around it, you may find this a productive read. As an intermediate jQuery developer I think you will find the mid chapters of most value. I’m not so certain I could say this fills a niche in the market in jQuery literature that was missing, but choice isn’t necessarily a bad thing. I wish there was more new in it. Just be aware of what is in this book relative to its competitors, and choose wisely.

(3 out of 5 stars)