Dependency

The Java world has Maven and Ivy.  Tools meant to untangle dependency webs, to get you what you need, when you need it and put it where you want it.  I've seen a few attempts over the years to adapt Maven to handle javascript dependencies.  They were abandoned unfinished.  I haven't looked much in the last year.

Javascript development is immature.  Like Java 10 years ago, you generally need to manage the resources manually.  It's up to you to juggle version control, version numbers and untangle the web of dependency.  Once you have your libraries in their proper versions and understand what order you need them in, there are tools to help you execute what you decide/know.  RequireJS, yepnode.js, and Grunt interest me the most so far, but they all have different priorities and all get involved late in the dependency management problem. They help you execute deployment and development, but only after you have manually resolved all your dependencies.

Programmatic resolution is hard. To do it well requires organized public repositories, which require standardized naming, versioning, and dependency declaration. Not to mention bandwidth. The person and/or organization that takes it upon themselves to get this rolling in the javascript world has a lot of work cut out for them. But plenty of reward as well.

Ender does programmatic resolution, and it's package.json could probably be made to do more, but it only seems to run just one level deep, when a deep, tangled dependency web is the inevitable reality of any modular application development. It also neglects script loading, test running, support for app code, and stands as a competitor to other frameworks, not a complement.

Dependency management in the javascript world is harder than Java because javascript doesn't require compilation. Compilation funnels all Java devs through a common build step, making a natural insertion point for a dependency management tool. Javascript lacks that chokepoint. Testing, linting, minimizing, concatenating--all of these have some potential but are still inconsistently used or only used in production deployment, not development. And both deployment and development themselves often are embedded within build/deploy processes for whatever other platforms are being used to build the server side of the web app. Any javascript build process ultimately needs to work as a subprocess of those builds.

Javascript/HTML5 as a platform is still wild, untamed by the build tools and processes that smooth out other application development environments.  What i would really love to have in taming it is a dependency management tool that works with these features:

• Repository support - public would be great, easy tools or conventions for private ones are acceptable. CDNs only get us part-way there; wheel authors need to be able to post libraries.
• Standards for declaring dependency info - to optimize performance and untangle the web this should support/require:
• library name and version
• CDN URLs for the library
• global variables exposed by the library
• the libraries dependencies
• name
• version (range)
• when needed (execution, document-ready, window-load, optional, etc)
• license/copyright info
• Conditional script loading (for polyfills)
• Easy, declarative switching between development (test and lint, but no minimization or concatenation) and deployment (minimize and maybe concatenate)
• Plugins for easy integrating with other build tools (Ant/Maven/etc)

Support for non-browser javascript and things like passing modules into each other (to avoid global exposure) are bonuses.  I don't care about them currently, but other people will.

A large portion of the code seems to be out there.  Grunt build process, Ender dependency resolution, yepnope script loading, and you're already well on your way. If you build it, they will come. Well, i certainly will! I'd built it myself, but there are only so many hours in a day.


#javascript

Readable Code

Code needs to be readable.  Readable code is debuggable, re-inventable and extendable.  But not everyone seems to know what makes code readable.

Occasionally, programmers will use comments to explain their code.  Comments certainly can help make a section of code understandable, assuming the comments are intelligible and up to date with the code.  But they in no way make code itself readable.

    Comments should only ever be used to say things that the code itself cannot be made to say.

In other words, you can use comments to explain why a piece code is there, but not to explain what the code is doing.  Yes, there are legitimate exceptions to that explanation, but again, those all fall under the first statement.

Mindful of the value of self-documenting code, many programmers create code like this:

AddressMapper.prototype.setInitialLocation = function(initialLocation) {
    this.initialLocation = initialLocation;
};
AddressMapper.prototype.setContainerElement = function(containerElement) {
    this.containerElement = containerElement;
};
AddressMapper.prototype.renderMapWithEffect = function(effect) {
    //magic!
};
// and so on...

After all, this is self-documenting, understandable code.  No one can accuse them of being opaque or obscure, right?  Beware the evils of premature optimization, right?  YUI 2 was like this, so it's ok, right? No, it most certainly is not OK.  And YUI 2 made me want to cry.

While long, descriptive names are indeed much better than inscrutable acronyms and abbreviations, they do not always produce code that can be called readable.  The example above, is unreadable because it is repetitive, mind-numbing, finger-cramping blather. When code gets repetitive like this, eyes gloss over and even stupid bugs find it easy to hide. Granted, they are likely to do that no matter what, but code like this does not help. And it gets worse, when you create APIs like this, the app code using it ends up just as obnoxious:

var addressMapper = new AddressMapper();
addressMapper.setInitialLocation('Portland, OR');
addressMapper.setContainerElement($('#portlandMap')[0]);
addressMapper.renderMapWithEffect(AddressMapper.Effect.SLIDE_DOWN);

Verbosity is contagious. It spreads. It infects. It sucks the will to live.

When reinventing a wheel, you are not designing an independent feature.  You are creating an API.  Yes, the wheel must be able to roll and so the raw, unadorned functionality of the code is your priority.  But ugly wheels make for ugly vehicles, and no one wants those.

Readable wheel code must avoid needless repetition and be designed to encourage readable app code.  Now, imagine this fictional plugin as a jQuery plugin:

var map = $.fn.map = function(address, effect) {
    return this.each(function() {
       render(this, address, effectFunctions[effect]);
    });
};
function render(el, address, effectFn) {
    // magic!
};
var effectFunctions = {
    slideDown: function(){...},
    ...
};

Which leads to user code like this:

$('#portlandMap').map('Portland, OR', 'slideDown');

<div id="#portlandMap"></div>

The repetition has dropped to tolerable levels, but it's not exactly a picture of readability.  Let's take it a step further and follow all the Rules for Reinvention:

var map = $.fn.map = function() {
    return this.each(map.render);
};

map.render = function(element) {
    var $el = $(element),
        address = $el.attr('address'),
        effectFn = map.effects[$el.attr('effect')];
    // magic!
;
map.effects = {
    slideDown: function(){...},
    ...
};

$(document).ready(function() {
   $('map').map();
});

<map address="Portland, OR" effect="slideDown"/>

At this point, the plugin code is not only more readable, but the app code has become pretty much ideal--declarative, minimal and extremely readable.  In the end, this should always matter most.  Sometimes, for whatever reason, there will be an irreducible amount of complex, ugly code.  In such cases, you should always strive to absorb that mess into your library and keep your app code clean and neat.

                           A readable API takes priority over readable internal code.

In fact, the lower "level" a library runs at, the less readability matters (and the more test code does!)  Since wheel code is just one small step away from app code, your wheels should still be highly readable wherever possible.

More Fun With Custom Events - state.js

My web apps these days are typically a single page, perhaps excepting a login page or some help content.  One page, composed from many files--during development, at least--does most of the work.  This design obviously began with the usual problems of lacking browser history control and bookmark-ability.  Looking at solutions others made, as you might expect, prompted me to reinvent another wheel.

Lo, state.js:

This enables browser history and bookmarks, by shoving simple key/value pairs into either the query string or the hash, as supported.  Keeping everything in the hash for all browsers would have been simpler, but then it would not survive a server-side login redirection process, undermining the ability to effectively bookmark a gated app.

state.js keeps track of the key/value pairs in memory, in order to notify listeners when those values are changed by the browser/user.  You can register a listener directly with state('foo', listenFn) or just watch for 'foo.state' events on the document.  This latter feature is part of the most interesting feature of state.js: it can be used entirely via custom events.  You do not need to ever directly reference the 'state' function in your app code or other js libs.  Granted, if you want soft dependency like this, it is easy to just have your config code wait for document ready and check if 'state' is available, but as state.js is such an event-oriented bit of code to begin with, i found it useful, amusing, and trivial to add an event-based API.

As an example, this:

state('foo', function(val, oldVal) {
    console.log('foo changed from ',oldVal,' to ',val);
});
state('foo', 'bar');// set foo to bar

is equivalent to this:

$(document).on('foo.state', function(val, oldVal) {
    console.log('foo changed from '+oldVal+' to '+val);
})
.trigger('state', ['foo','bar']);// set foo to bar

And here's the other useful features:

var all = state();// get a copy of current state
var foo = state('foo');// get current 'foo' state
$(document).trigger('back');// tell the browser to go back a page
$(document).trigger('forward'); // === history.forward()

As you can probably guess, this event-based API comes in quite handy when using trigger.js.  Now your page's controls can control state values and shift browser history:

<button trigger="nextPg state['pg',2]">Next</button>
<button trigger="back">Back</button>

HTML Validators Considered Harmful

There are these things out there called "HTML validators".  The last time i tried one was about 12 years ago.  There's a reason i haven't gone back.  It's not that i don't believe in standards; i do.  It's not that i'm sloppy or sneer at perfectionism; i don't!  I don't use HTML validation, because it doesn't work, won't work and shouldn't work.

HTML validation doesn't work because the browsers have never even come close to uniform standards coherence.  So the validators are testing markup against pure fiction, an idealistic but flawed dream of W3C hegemony.

HTML validation won't work because both HTML and browser versions are toast.  Over and done.  HTML has officially been declared what it always was: a fuzzy target.  Browsers have begun a version number war.  It is accepted dogma in web app development that you are doing it wrong when you check the user-agent string for any browser or version number.  Feature detection is the new game, and javascript is now used to emit so much markup into the document that HTML validators are a hopeless cause.

HTML validation shouldn't work, because it has always been worse than useless. It is constricting, a bane to innovation.  Why should app developers and wheel reinventors be restricted to a generic set of elements and attributes?  What good does it accomplish to place such a limit?  Like many other languages, HTML/XML is designed to be extended.  That creative ability should not be left only to the W3C and browser vendors.

In practical terms, browsers are spectacular at one thing, above all else: ignoring things.  They ignore extra whitespace, unrecognized elements, custom attributes, and even unclosed tags in many cases.  They do this so well out of necessity. Standard specifications have never been met.  They also need not only a high degree of backward compatibility, but forward compatibility as well.

Browsers are designed for new things.  Be creative!


The only valid kind of HTML validation is syntax validation.  All i ever want to know is if it is parse-able.  Really, that's it!

Another Short Cut - key.js

Keyboard shortcuts are a wheel that just begs for reinvention.  And being the sucker i am, i gave in and wrote me a new wheel just for that.

Like trigger.js, this is about better events and giving page controls control.  Jump below the gist for explanation:


This does two things:

• allows keyboard shortcuts to be assigned in HTML
• triggers namespaced, natural language 'key' events

<a key="alt-r" href="#reply">Reply</a>
<button key="home">Start Over</button>

$('#foo').on('key.ctrl-delete', Foo.deleteAll);

Both behaviors do not by default happen for most "plain" key events (roughly /[a-zA-Z0-9]/) unless you set key.all = true or add a 'key-all' class to your page's root tag (i.e. <html class="key-all">).

For the HTML shortcuts, key.js triggers 'click' events as appropriate. If you need a different event, add a trigger="different" and use trigger.js to translate the click.

key.js also provides a key() function to jQuery to let you trigger key events from javascript, as is quite necessary for testing your key events and shortcuts.

Obviously, if you look at the code, there are a great many keyCode values for which this wheel does not provide an English translation. At this point, 100% completeness seems both difficult (due to OS variation) and largely useless. Almost all "normal" keyboard shortcuts are accounted for, and any developer using this code can easily add more to key.codes. As with most of my wheels, this one is quite adjustable and extensible. Enjoy!

Give Controls Control - trigger.js

When you put a <button> or an <a> or an <input type="image"> into your markup, you intend them to do something, not just sit there and look pretty.  This inevitably means writing code like this:

$('a.blah').on('click', function() {
    console.log('blah');
});

STOP!  You actually meant to use a custom event, right?  Let's try that again:

$('a.blah').on('click', function() {
    $(this).trigger('blah');
});
$(document).on('blah', function() {
    console.log('blah');
});

Ah, much better. Sure, it's longer, but this way you are self-documenting and making your code easier to test, extend and maintain.

But what if it didn't really have to be longer? What if the button itself could be told to trigger the custom event. After all, that ".on('click'...)" business is just boilerplate and not particularly friendly to the world of keyboard accessibility. Well, this is what trigger.js does for you. Instead of setting up the custom event with some boilerplate javascript, we just extend HTML with a 'trigger' attribute:

<a trigger="blah">Blather</a>

$(document).on('blah', function(e) {
    console.log('blah');
});

Now there's no "blah blah blah" boilerplate; i get to focus on what i'm doing more than how i'm doing it.  It gives my controls control, rather than shoving their functions off into a separate file.  And this can be extended to accomplish even more.

But before we talk about the "more", here is trigger.js:


Wait, you say! Why isn't it just like this:
It could be that simple, true. If that's all you need, use that. But it's hard to resist adding a little flair when you are inventing the wheel. The first thing i wanted was sequenced events.  Why trigger just one when you can trigger more? After all, i like to "use custom events like crazy", and many "actions" in applications are actually combinations of sequential, dependent, but separate actions. Consider:

<button trigger="validate submit">Submit</button>

This way, my "validate" code doesn't have to be tied to "submit" code and so on.  And when "validate" fails, it can still call e.preventDefault() to keep "submit" from firing.

Once i had sequenced events in my markup, it was natural and easy to add them to jQuery's trigger function, especially for debugging things in the console.

$('#cancel').trigger('reset back');

That done, i remembered that i have long wanted to have my own custom event properties.  Instead of "moveUp" and "moveDown", i wanted to have "move" events where i could test for "up" or "down" properties, just like i test e.ctrlKey.  So, trigger.js now supports:

<button trigger="move:up next">Up</button>

$('#game').on('move', function(e) {
    var roll = dice.value();
    if (e.up) player.climb(roll);
    if (e.down) player.slide(roll);
    if (player.winner) {
        e.preventDefault();// all done
    }
}).on('next', function() {
    player = player.next();
});

Finally, i occasionally envied the ability to associate data with an event, like you can when calling trigger() on a jQuery collection. So i added that as well:

<button trigger="level[10]">Loud</button>
<button trigger="level[11]">Spinal Tap</button>

$(document).on('level', function(e, level) {
    speakers.goTo(level);
});

And finally, i wanted my apps to be more keyboard accessible. So, trigger.js also listens for 'enter' events on elements that don't naturally convert them to clicks (div, span, a[!href]) and does that for them.

By all means, if these extra features aren't useful to you, just use the simple, four-line version. But if you want to give your document's controls a bit more control, trigger.js is ready to help. :)