Introducing conditional.js, a jquery plugin for clean predicate-action separation

These days javascript space is full of newly developed and emerging frameworks. It is still early to speculate which ones will make it and can become par to jquery's unique status, but some have already made it into quite a few production projects and are gaining momentum and popularity by the day.

Depending on your background - be it Open Source Java/Ruby/Python or Microsoft's .NET - examples could be different but one is the MVVM Framework for javascript - aka knockout. I have been and am a fan of all the possibilities this framework brings to the client-side code but sometimes all you need is a simple tool to organise your code and make it more readable - you do not need a full-fledged MVVM library.

Let's bring an example.

Consider we have a form where depending on the answer to one question, answering some other questions become mandatory. We have a form asking for our detail and if the answer to marital status from a dropdown is "married", then detail of the spouse needs to be provided.

If we were to build this in HTML/javascript, we would put the fields for spouse detail in a container and then hide/show based on the value selected from the dropdown.

Here we have a predicate: "whether marital status of married is selected" and we have an action which is "show or hide a container". Here the action is parameterised with a boolean which happens to be the return value of the predicate.


Coding this is almost trivial: use jquery (or plain old DOM events) to subscribe to changes of the dropdown value and hide/show accordingly. And none of that predicate/action nonsense!


But as the requirements gets more complex, the code gets more and more complex to the point where the intention of the code is buried underneath many lines of code. For example, what if the logic depends on the value of multiple fields? The complexity will increase exponentially with the number of fields involved. Also one common problems - those of you who have implemented such scenario would immediately remember - is that when the value is served by the server, the event is not triggered so the visibility of the container is not affected. For example, if we edit a saved form for a married person, server will send the HTML with the value of married status dropdown to "married", however, since the change event is not triggered, spouse detail container stays hidden. To combat this, we have to raise the change (or call the callback code) so that the logic is executed.

One solution is to use a framework such as knockout to wire the event with the logic as a client-side binding. One problem with such approach is that the binding to multiple fields is cumbersome, especially if they are involved in more than one such logic. Also, implementing custom action requires adding custom binding which is fine with one or two cases but not great when there are more custom action to be executed.

The solution conditional.js presents here is to a separation of predicate and action by:

1. Subscribe to change events of one or multiple elements by providing one or more jquery selectors
2. Accepting a predicate (a javascript callback function) that will receive the value of the elements
3. A set of standard actions (hide/show and enable/disable) that will react to the value returned by the predicate. Alternatively registering a custom action, or simply just providing a callback action that will be called passing the return value of the predicate.

This probably sounds more complex than it is so let's bring the example - example above but this time with code.

        $("#spouseContainer").conditional({
            selectors: "#marst",
            predicate: function (maritalStatus) { return maritalStatus==="Married"; }
        });

As can be seen above, container with id of "spouseContainer" is used to start create the jquery object. We pass selectors (here a single string and it can be a string array too) that is for the marital status dropdown with id of "spouseContainer" and then a predicate defining our desirable condition which by default is visibility - i.e. whenever value of "marst" is equal to "Married", spouseContainer will be visible. Since we have passed a single selector, our predicate needs to accept a single parameter.

So I believe this 3 lines of code are really expressive and readable. This also take care of the problem of setting the status when the page is loaded with the desirable value.

In the next blog, I will delve into all options and possibilities of conditional.js.

Upgrading your jquery to 1.6+ is safe, really?

Upgrading dependencies are always a risk. A risk that sometimes can be qualified but from my personal experience when things go wrong, they are usually where you least expect them. While performing a thorough "impact analysis" is helpful, this is easier said than done. And usually just a tick in the box, meaning yes we did it (technically covering our back). In my case, we planned our upgrade from 1.4 to 1.5 but this time, we had to use a jquery plugin which we realised in the middle of the sprint that it used 1.6 features.

We all love jquery, not only because it has made working with DOM easier but also because it is such a forgiving framework, tries to guess your intentions and return you what you intended and not necessarily what you asked for. Well, we will see how this could affect the risk of upgrading to jquery 1.6+ (currently at 1.7). But to be honest out of all libraries, jquery was the one I would least to expect a breaking change - it is a library that hides breaking differences of browsers so knows the pain of a breaking change!

According to jquery release note, upgrading to jquery 1.6.1 should not require any change:

With the introduction of the new .prop() method and the changes to the .attr() method, jQuery 1.6 sparked a discussion about the difference between attributes and properties and how they relate to each other. It also came with some backwards compatibility issues that have been fixed in 1.6.1. When updating from 1.5.2 to 1.6.1, you should not have to change any code.

 OK, I am relieved! So I can happily upgrade our jquery 1.5 to 1.6.1 (and even better 1.7). Is it really safe? Well, the answer depends on how you have used (or abused) the method attr() on previous versions.

attr() vs. prop()

All the difference between v 1.5 vs. 1.6 boils down to introduction of prop() and change of the semantics of the existing attr() that can break your code, well it did ours - unfortunately I believe due to our bad jquery code. prop() will represent the semantic of the property which could have been stored as an attribute while the attr() will return literal (string) value of the attribute.

Confused? Well, I believe origin of the confusion was the poor HTML attribute definition - let's blame W3C here, they always get blamed anyway! To explain it further, if I have a checkbox that is checked, its "checked" property will be true but its "checked" attribute will be "checked".

In code terms, let's imagine this scenario:

<button name="chip" id="chap" disabled="disabled">happy chappy</button> 
<input type="checkbox" id="chk" checked="checked">Hello</input>


As you can see we have to elements, a checked checkbox and a disabled button.

This is how this is going to look in jquery 1.5 (jsfiddle line here)

console.log("disabled attr: ", $("#chap").attr("disabled")); //outputs "disabled attr: true"

console.log("checked attr: " + $("#chk").attr("checked")); //outputs "checked attr: true"

This is how this is going to look in jquery 1.6 (jsfiddle link here)

console.log("diabled attr:", $("#chap").attr("disabled")); // disabled attr: disabled
console.log("checked attr: " + $("#chk").attr("checked")); // checked attr: checked
console.log("diabled prop: ", $("#chap").prop("disabled")); // diabled prop:  true
console.log("checked prop: " + $("#chk").prop("checked")); // checked prop: true

Will attr() always return the literal value of the attribute? No, and that is what confuses me but again I think it is partly due to inconsistencies of HTML attributes. For example, value of the disabled attribute does not have to be "disabled" to be effective, its mere existence signifies "disabledness" of the element. For example, if the attribute has no value, element is still disabled (or checked) and attr() will return element's implied value and not the literal one (which I believe should not be so and attr() should just stick to the literal value):

<button name="chip" id="chap" disabled>happy chappy</button> 
<input type="checkbox" id="chk" checked>Hello</input>

console.log("diabled attr:", $("#chap").attr("disabled")); // disabled attr: disabled
console.log("checked attr: " + $("#chk").attr("checked")); // checked attr: checked

Where can it cause problems


We experienced two types of problems:

1. Calling  $("#chap").attr("disabled", "") will totally remove the attribute (enable the element) in jquery 1.5, while in jquery 1.6 it will just set the value to empty string. So my colleagues have been conveniently using attr("disabled", "") to enable the element while they should have just used removeAttr() which has been there since v1.0. Semantically, attr("disabled", "") should set the attribute to empty string but jquery used to gracefully interpret that as the same as setting property to false - not anymore.
2. If you use the literal value of the attr() since it would return false/true but now it will return "disabled"/undefined. In our case the value was being passed to the server, hence server was expecting a boolean (false/true) and it broke when it saw "disabled"/undefined!

Conclusion

Upgrading your code from jquery 1.5 to 1.6 can break your code around the attr() function. So be careful and plan a full regression testing after the upgrade.