Fluent APIs and Method Chaining

Monday, May 13, 2013

Of the vast catalog of Design Patterns available at our disposal, often times I find it is the simpler, less prominent patterns which are used quite frequently, yet recieve much less recognition; a good example of which being the Method Chaining Pattern.

Method Chaining

The Method Chaining Pattern, as I have come to appreciate it over the years, represents a means of facilitating expressiveness and fluency when used articulately, and mere convenience in it’s less sophisticated use-cases.

Design Considerations

When considering Method Chaining, one should take heed not to simply use the pattern as merely syntactic sugar from which writing fewer lines of code can be achieved; but rather, Method Chaining should be used, perhaps more appropriately, as a means of implementing Fluent APIs which, in turn, allow for writing more concise expressions. By design, such expressions can be written, and thus read, in much the same way as natural language, though they need not be the same from a truly lexical perspective.

The resulting terseness afforded by Method Chaining, while convenient, is in most cases not in-of-itself a reason alone for leveraging the pattern.

Implementation

Method Chaining, when considered purely from an implementation perspective, is perhaps the simplest of all design patterns. It’s basic mandate simply prescribes returning a reference to the object on which a method is being called (in most languages, JavaScript in particular, the this pointer).

Consider the following (intentionally contrived) example:


var Chain = function(val){
    this.init(val);
};
var fn = Chain.prototype;
fn.init = function(val){
    this.links = isNaN(val) ? 0 : val;
};
fn.addLinks = function(val){
    if (!isNaN(val)) {
        this.links += val;
        this.links = this.links < 0 ? 0 : this.links;
    }   
    return this;
};
fn.removeLinks = function(val){
    if (!isNaN(val)) {
        this.links -= val;
        this.links = this.links < 0 ? 0 : this.links;
    }   
    return this;
};

var chain = new Chain();
console.log(chain.addLinks(10).removeLinks(5).links); // 5

var Chain = function(val){

this.init(val);

};

var fn = Chain.prototype;

fn.init = function(val){

this.links = isNaN(val) ? 0 : val;

};

fn.addLinks = function(val){

if (!isNaN(val)) {

this.links += val;

this.links = this.links < 0 ? 0 : this.links;

}

return this;

};

fn.removeLinks = function(val){

if (!isNaN(val)) {

this.links -= val;

this.links = this.links < 0 ? 0 : this.links;

}

return this;

};

var chain = new Chain();

console.log(chain.addLinks(10).removeLinks(5).links); // 5

As can be seen, implementing Method Chaining requires nothing more than simply having methods return a reference to this.

API Simplicity

Method Chaining is typically used when breaking from traditional Command Query Seperation (CQS) principles. The most common example being the merging of both getters (Queries) and setters (Commands). I especially like this technique, as, aside from being very easy to implement, it allows for an API to be used in a more contextual manner from the developers perspective as oppossed to that specified by the API designer’s preconceptions of how the API will be used. For example:


var Messenger = function(msg){
    this.val = msg || '';
};
var fn = Messenger.prototype;
fn.message = function(msg){
    if (msg){
        this.val += msg + ' '; 
        return this;
    }
    return this.val;
};
console.log(new Messenger().message('Hello, World').
.message()); // Hello World

var Messenger = function(msg){

this.val = msg || '';

};

var fn = Messenger.prototype;

fn.message = function(msg){

if (msg){

this.val += msg + ' ';

return this;

}

return this.val;

};

console.log(new Messenger().message('Hello, World').

.message()); // Hello World

As can be seen, the message method serves as both a getter and setter, allowing users of the API to determine how the method should be invoked based on context, as well as affording developers the convenience of needing only to remember a single method name. This technique is used quite heavily in many JavaScript libraries and has undoubtedly contributed to their success.

We could further expand on this concept by determining a method’s invocation context based on the arguments provided, or the types of specific arguments, thus, in turn, merging various similar methods based on a particular context.

An important design recommendation to consider is that if you are writing an API which violates CQS (which is quite fine IMHO), as always, API consistency is important, thus all getters and setters should be implemented in the same manner.

Fluency

As was mentioned, in most cases, Method Chaining is leveraged to facilitate APIs which are intended to be used fluently (e.g. an Internal DSL). Such implementations typically provide methods which, by themselves, may have little meaning; however, when combined, allow for writing expressions which are self-descibing and make logical sense to users of the API.

For example, consider the way one might describe a Calendrical Event:

Vacation, begins June 21st, ends July 5th, recurs Yearly.

We can easily implement a Fluent API such that the above grammar can be emulated in code as follows:


var Event = function(name){
    ...
};
var fn = Event.prototype;
fn.begins = function(time){
    ...
    return this;
};
fn.ends = function(time){
    ...
    return this;
};
fn.recurs = function(when){
    ...
    return this;
};
var vacation = new Event('Vacation');
vacation.begins('June 21st'').ends('July 5th').recurs('Yearly');

var Event = function(name){

...

};

var fn = Event.prototype;

fn.begins = function(time){

...

return this;

};

fn.ends = function(time){

...

return this;

};

fn.recurs = function(when){

...

return this;

};

var vacation = new Event('Vacation');

vacation.begins('June 21st'').ends('July 5th').recurs('Yearly');

The same methods can also be chained in different combinations, yet yield the same value:


var vacation = new Event('Vacation');
vacation.recurs('Yearly').ends('July 5th').begins('June 21st'');

var vacation = new Event('Vacation');

vacation.recurs('Yearly').ends('July 5th').begins('June 21st'');

Given the above example, we could further improve on the fluency of the implementation by adding intermediate methods which can, by themselves, simply serve to aid in readability, or, provide an alternate modifier for chaining:


var Event = function(name){
        ...
};
var fn = Event.prototype;
fn.begins = function(time){
    ...
    return this;
};
fn.ends = function(time){
    ...
    return this;
};
fn.recurs = function(when){
    ...
    return this;
};
fn.on = function(when){
    ...
    return this;
};
fn.at = function(when){
    ...
    return this;
};
fn.every = function(when){
    ...
    return this;
}; 

var vacation = new Event('Vacation');
vacation.begins.on('June 21st').at('5pm').ends.on('July 5th').at('11pm').recurs.every('Year');

var Event = function(name){

...

};

var fn = Event.prototype;

fn.begins = function(time){

...

return this;

};

fn.ends = function(time){

...

return this;

};

fn.recurs = function(when){

...

return this;

};

fn.on = function(when){

...

return this;

};

fn.at = function(when){

...

return this;

};

fn.every = function(when){

...

return this;

};

var vacation = new Event('Vacation');

vacation.begins.on('June 21st').at('5pm').ends.on('July 5th').at('11pm').recurs.every('Year');

When implementing Fluent APIs, we can design such that different logical chaining combinations can yield the same result, thus affording users of the API the convenience of determining the most appropriate expressions based on context or personal preference, even grammatically so. Illogical chaining combinations can be handled by either throwing an exception, or they can simply be ignored based on the context of a preceding invocation – though, of course, one should aim to avoid designs which allow for illogical chaining.

The Ubiquitous Example – jQuery

While Method Chaining and Fluent APIs, as with most design patterns, are language agnostic, in the JavaScript world perhaps the most well known implementation is the jQuery API; for example:


$('#test').css('color','#333').height(200);

$('#test').css('color','#333').height(200);

In addition to jQuery, there are numerous additional JavaScript Method Chaining and Fluent APIs of note, Jasmine in particular has a very expressive API which aligns excellently with it’s design goals. The various libraries which implement the Promises/A spec also provide very clear and concise Fluent APIs.

Concluding Thoughts

Over the years I have leveraged Method Chaining to facilitate the design of Fluent APIs for various use-cases. The two patterns, when combined, can be especially useful when designing Internal DSLs; either third-party libraries, or APIs specific to a particular business domain.

Agile ⋅ APIs ⋅ Code Review ⋅ Design Patterns ⋅ JavaScript ⋅ Object Oriented Design ⋅ Refactoring ⋅ Software Engineering

No comments

GitHub Quick Tip

Wednesday, April 3, 2013

Recently, I was looking for a simple way to view an html page which is part of a GitHub project’s source. In particular, I wanted to provide links on the Backbone.EventBroker project’s main page so users could run the specs and view the example.

Fortunately, as is the case with most things on GitHub, this is quite easy to accomplish; requiring nothing more than appending the URL of the page in the projects source to the http://htmlpreview.github.com/? query string:


http://htmlpreview.github.com/?https://github.com/<username>/<project-name>/blob/<path/to/page>.html

http://htmlpreview.github.com/?https://github.com/<username>/<project-name>/blob/<path/to/page>.html

Simple and useful indeed!

Git ⋅ Quick Tips

No comments

Pseudo-abstraction in Backbone

Friday, March 29, 2013

As has been mostly disseminated, JavaScript, being a dynamic, prototypal language, affords developers the ability to design outside the rigid confines inherent to statically typed languages. Interestingly, perhaps even somewhat paradoxically, this same flexibility also allows for programmatically simulating specific features commonly found in statically typed languages, if desired.

While JavaScript does not have a traditional type system, nor does it provide traditional constructs by which user defined types are specified, it is still, necessarily so, a common and desirable design goal to implement a system with the notion of classes in order to provide data types which encapsulate domain logic and facilitate reuse; both of which being key design attributes which help mitigate the complexity of large applications.

Nearly all JavaScript MV* frameworks provide such facilities, and do so in a consistent and convenient manner; most of which allowing for practical circumvention of the prototype system almost entirely. It is also worth noting that while most libraries themselves are generally implemented in the succinct and terse, large applications typically call for a more traditional object oriented design, while also being prudent to do so in alignment with the conventions and idioms particular to JavaScript itself.

Abstraction

At times it will be necessary to design a system with reusable abstractions. In fact, it is quite hard to imagine a modern SPA of even marginal complexity as being maintainable without some level of base class functionality.

For instance, it can be particularly useful to implement base Models and Collections which provide general functionality common amongst all Models and Collections; such as the parsing and appropriate routing of service API exceptions to error callbacks, and successful service results to success callbacks, and so forth.

Since such base classes generally do not provide any concrete behaviors themselves (hence the abstraction), they are of considerable value, specifically when reused amongst various large scale, distributed projects; and, from a design perspective, it is often important for one to ensure such classes are only used as intended.

While one can convey the intended usage of a base class easily enough simply by means of comments alone, indicating their usage as such (and that is quite fine if you prefer), it is also just as easy to ensure base classes are only used as intended programmatically by implementing a simple conditional which checks an instance’s constructor against the base class’ constructor function. For example (in the context of backbone, though any framework applies):


var SomeBaseModel = Backbone.Model.extend({
    initialize: function() {
        if (this.constructor === SomeBaseModel){
            throw new Error('SomeBaseModel must be extended');
        }      
        console.log('SomeBaseModel.initialize');
        ...
    }
    ...
});

new SomeBaseModel();
// ReferenceError: SomeBaseModel must be extended

var SomeBaseModel = Backbone.Model.extend({

initialize: function() {

if (this.constructor === SomeBaseModel){

throw new Error('SomeBaseModel must be extended');

}

console.log('SomeBaseModel.initialize');

...

}

...

});

new SomeBaseModel();

// ReferenceError: SomeBaseModel must be extended

Then, one can simply extend the base class, invoking defaults as needed:


var SomeModel = SomeBaseModel.extend({
    _super: SomeBaseModel.prototype,
    initialize: function() {
        this._super.initialize.call(this);
        console.log('SomeModel.initialize');
    }
});

new SomeModel();
// SomeBaseModel.initialize 
// SomeModel.initialize

var SomeModel = SomeBaseModel.extend({

_super: SomeBaseModel.prototype,

initialize: function() {

this._super.initialize.call(this);

console.log('SomeModel.initialize');

}

});

new SomeModel();

// SomeBaseModel.initialize

// SomeModel.initialize

Concluding Thoughts

Like many in the JavaScript community, I, too, am of the opinion that JavaScript should not be made to reflect that which is common to other languages simply for the sake of familiararity; but rather, one should be prudent to leverage the flexiblity inherent to the language itself, and this example serves as a demonstration of how such flexibility can be utilized to provide what a specific design calls for at the discretion of the developer.

Agile ⋅ Backbone ⋅ Code Review ⋅ Design Patterns ⋅ JavaScript ⋅ Object Oriented Design ⋅ Refactoring ⋅ Software Engineering

No comments

Natural Box Model Sizing

Thursday, February 14, 2013

As Web Developers, the benefits to be afforded by simply taking the time to aquire a fundamental understanding of CSS layouts can not be overstated; for it is these very skills that provide the basis from which designs can be achieved with ease; making the task of designing the Web an enjoyable, and rewarding experience. Conversely, without an understanding of core concepts, one is certain to spend a significant amount of time – often in frustration – attempting to achieve a desired layout.

CSS Layout Fundamentals

In the context of CSS layouts, such fundamental concepts to be considered (in no particular order) include: document flow, positioning, display types, off-sets, floats, overflows, clears, and the like; and, as the title of this article suggests, the Box Model.

The Box Model

I emphasize the importance of the Box Model here in particular, as the default sizing of elements with respect to the Box Model is quite the opposite of what one might expect.

For example, consider the following:


.box {
    width: 200px;
    height: 200px;
    padding: 20px;
    border: 1px solid #333;
}

.box {

width: 200px;

height: 200px;

padding: 20px;

border: 1px solid #333;

}

As many would assume, any element with the .box class would render with a 1px border and 20px of padding, at exactly 200x200px. However, by default, this is not how elements are sized, but rather, the actual size of a rendered element is calculated to include both borders and padding in addition to width and height, the calculation for which essentially being:


total width  = left border width + left padding + 
               width + 
               right padding + right border width;
total height = top border width + top padding + 
               height + 
               bottom padding + bottom border width;

total width = left border width + left padding +

width +

right padding + right border width;

total height = top border width + top padding +

height +

bottom padding + bottom border width;

This results in nearly all elements (form elements notwithstanding) being measured quite differently then one might have expected. Thus, in the example of the .box class mentioned above, rather than elements being rendered at the expected 200x200px, as defined by their respective width and height properties, they would instead be rendered at 242x242px.

One could argue that in the majority of cases, this is neither what is expected nor what is desired. Fortunately, CSS3 offers the very useful property box-sizing, which can be used to override the default sizing of elements (content-box), and allow for sizing them more naturally simply by setting box-sizing to border-box:


.box {
    /* set 'border-box' to size as expected */
    box-sizing: border-box;
    width: 200px;
    height: 200px;
    padding: 20px;
    border: 1px solid #333;
}

.box {

/* set 'border-box' to size as expected */

box-sizing: border-box;

width: 200px;

height: 200px;

padding: 20px;

border: 1px solid #333;

}

By setting box-sizing: border-box, elements with the .box class will render at the expected size, 200x200px, as defined by the width and height properties; with the content area being 158px, padding 40px, and border at 2px.

Box-sizing Global Resets

Paul Irish has a great solution for this very problem whereby a global reset is used to ensure all elements are sized with border-box. I highly recommend this approach as it provides a starting point from which all elements will be sized “naturally”. The reset is simple, safe, and works perfectly well in supported browser:


* {
    /* set 'border-box' to size as all elements */
    box-sizing: border-box;
}

* {

/* set 'border-box' to size as all elements */

box-sizing: border-box;

}

CSS3 background-clip and background-origin

The background-clip and background-origin properties, respectively, can both be used in tandem with box-sizing; each accepting the same values as that of box-sizing, allowing for related control of how backgrounds are displayed for elements with respect to the Box Model.

Concluding Thoughts

It was quite some time ago while trying to understand how the sizing of elements is determined in more detail that I first learned of the box-sizing property. In the time since, I have been using box-sizing:border-box with great results and have really come to appreciate this property.

And so, if you haven’t leveraged box-sizing: border-box in your designs yet, I strongly recommend giving it a try, as you will likely find it to result in more “naturally” sized elements.

Browsers ⋅ CSS3 ⋅ HTML5

No comments

Windows 8 Web App Start Screen Tiles

Tuesday, February 5, 2013

Having had to certify a Web Application for use on the HTC Windows Phone 8X, as well as the Microsoft Surface Tablet, I was interested in providing a Start Screen Tile similar to that of the application’s current iOS Web Clip Icon. Not the least, the new Tile Based UI in Windows 8 presents significant UX improvements over that which has been seen in previous versions of Windows; thus, I felt compelled to take advantage of the new UI from a Web Application context.

Conveniently, adding a Windows 8 Start Screen Tile (Pinned Site) can be accomplished quite easily, and in much the same way as that which is used when specifying a Web Application to run in standalone-mode on iOS. To do so, one need only add additional meta elements with a name attribute of msapplication- followed by a specific Tile property. A standard content attribute can then be used to provide the corresponding attribute value.

For example, a Tile can be defined with a specific color using msapplication-TileColor:


<meta name="msapplication-TileColor" content="#333"/>

Likewise, a specific Tile image can be provided using msapplication-TileImage:


<meta name="msapplication-TileImage" content="/assets/img/tile-logo.png"/>

Note: Tile images should be 144x144px, in .png format (transparent).

This site, for instance, utilizes both of the above:


<meta name="application-name" content="Eric Feminella"/> 
<meta name="msapplication-TileColor" content="#ffffff"/> 
<meta name="msapplication-TileImage" content="/blog/img/tile-icon@144.png"/>

While creating and defining a Start Screen Tile is simple enough, Microsoft also provides a handy Web based utility which allows for automating the Pinned Site creation process by generating a selected Tile Image in the correct dimensions, and providing the corresponding source at www.buildmypinnedsite.com

Browsers ⋅ HTML5 ⋅ Mobile Web ⋅ Tablets ⋅ User Experience Design ⋅ Windows 8

3 comments