Category Archives: JavaScript

Coaxing Sound out of the Browser

Leave a reply

“Get someone else to blow your horn and the sound will carry twice as far.” – Will Rogers

Having the utmost respect for Will Rogers and his timeless wisdom, I must apologize to his memory for using this quote for purposes other than originally intended.  The quote struck me as somehow appropriate,  because I want to write a few words on the use of sound in browsers and I want to recommend the adoption of a particular JavaScript library to make this as painless as possible.  Rather than creating your own solution from scratch, in the final analysis I am going to suggest letting Howler.js “blow your horn” for you.

This article touches on developing pages and browser applications using sound  – past, present and future.  However, most of the article will be devoted to alternatives for using sound in today’s development environment and I’ll show you two different ways to do it.  A link to a working demo will be included at the bottom of the article and we will walk through the heart of the code that drives this demo, leaving you with two alternative modules for playing sound that you may freely incorporate into your own work.

In the beginning, there was silence.  The early days of browsers were devoid of any method to play any sound at all. Over time, some limited proprietary sound playing capability began to appear in different browsers, but this was essentially unusable.   Eventually, plug-ins appeared that made the playing of sound in the browser a reality.  One of these plug-ins, Flash, still enjoys some popularity even today, particularly as a fallback mechanism for out of date browsers that don’t support more modern methodologies.  However, most developers would rather not have to use a plug-in, which requires client-side installation and maintenance by users.  So a more modern built-in solution is typically preferable.

Enter the HTML5 Audio element.  HTML5 audio is the dominant form of sound expression in today’s browsers.  In fact, this mechanism is present in all modern browsers (see Can I use the HTML5 audio element).  More importantly, it works reasonably well for playing basic sounds in simple scenarios – although the implementation does differ significantly across different platforms and caveats abound.   Here I am tempted to begin describing the features of the HTML5 Audio element and contrasting their implementation in major browsers – however, that is not really the thrust of this article (though basics will be discussed) and that information can be found elsewhere on the web.  I’ll provide a link at the bottom of the article to detailed information on the HTML5 Audio specification.  I’ll also provide a link that discusses implementation limitations on some platforms – notably iOS with mobile Safari.  The topic of mobile Safari does figure prominently in one of the code examples that follow.

The wave of the future for playing sound in the browser appears to be an API known as Web Audio.  This is an open source, WC3 supported, Chrome-originated specification.  This specification is much more extensive and capable than the HTML5 Audio specification.  Unfortunately, though it currently enjoys support from modern web-kit browsers,  there is insufficient penetration in the browser ecosphere to be able to rely upon it as yet, unless you are targeting specific browser platforms (see Can I use the Web Audio API).  Earlier, I foreshadowed a conclusion made in this article by suggesting that Howler.js is the best way to implement browser sounds at this time.  One significant reason for this is that by default, Howler.js will use the Web Audio API, to play your sounds if support is present.  If it is not present, it will fall back to an HTML5 Audio solution.

Let’s focus on the present now and take a look at solutions that work and are broadly applicable today.  If you want to use sound in the browser today, it probably means that you will have at least some degree of reliance on HTML5 Audio – either directly using “native” JavaScript or else indirectly through some library such as Howler.js (since Howler.js will automatically fall back to using HTML5 Audio if it must).  It should be noted that there are other JavaScript sound libraries, but these tend to start with HTML5 Audio support and fall back to Flash support if HTML5 Audio is not supported.  While a Flash fallback is useful in a small number of scenarios, this has become increasingly unnecessary since HTML5 Audio support in modern browsers is nearly ubiquitous.  Personally I’d rather go with a forward-looking solution like Howler.js that tries to support that latest technologies and used HTML5 Audio as the fallback.

Here’s a quick review of the core ideas behind playing sound in the browser and using HTML5 Audio.   At the most basic level, the process of causing a browser to emit sound consists of two steps:

  1. Loading / pre-loading your sound resource(s).
  2. Playing your sound resource(s).

Regardless of which browser is involved, when employing HTML5 Audio it is the audio element that handles both of these tasks.  It will even provide a sound playing UI if you enable it.  For our purposes however, we would prefer to dynamically create an audio element with no visible UI, and use it from within JavaScript code to both load and play sounds.

Whether a static or a dynamic audio element is employed, or instead a dynamic audio element is used, the manner in which it works is configured by setting it’s attributes.  The following are the “most important” attributes and are enough to get started with – if your sound playing needs are fairly basic, it may be that you will need to set no other attributes.

  • The controls attribute – Add this to the element by itself (with no associated value) and it will enable the build-in sound playing API.  This is normally used when a static element is employed but useful to know about, even though neither code example in this article uses it.
  • The src attribute – This is used to define the sound resource (i.e., some file path or URL) that the element will act upon.
  • The preload attribute  – This is supposed to allow control of if and when the element will preload the sound (buffer it in memory) to minimize or eliminate lag between the request to play the sound and the actual playing of the sound.  If you do not specify a preload attribute, the default value of “auto” will be applied, which is pretty much what you’d always want anyway.  Unfortunately, some browsers – notably mobile Safari – ignore this setting and will refuse to preload, only loading sound after a user interaction is detected.

Aside from the above-listed attributes, there are only perhaps two more things more you must know about the audio element – how to know when a sound resource is ready to play and how to actually play it.  Some sound resources can be very large – for example, music files.  A significant amount of time can pass between initiation of preload and the ability to actually play a sound.  The canplaythrough event is useful in detecting when a sound has been loaded completely enough to be able to play it without problems.  Which leads us to the other thing you should know – the play method of the HTML5 audio element must be called from JavaScript code to actually play the sound if the built-in sound UI is not employed.

In short, using the HTML5 audio element is pretty easy - unfortunately the lack of a single standardized audio format and the uneven implementation of the specification across browsers presents difficulties to the web developer who would like to write once and run everywhere.   We’ll look at the worst of these difficulties and then examine work-arounds and approaches to deal with them.  Once this is out of the way, we’ll dive into some code, the implementation of which has been designed to avoid or minimize these difficulties.

Probably the first thing to consider and possibly the most significant, is to decide what audio format to use for your sound.  There are several formats available but here is a short-list of some of the most popular and summary comments on each:

  • The wav format -  On the plus side, this format provides good sound quality and is usable nearly everywhere – the most notable exception being Internet Explorer, which does not support wav except in the mobile version.  On the negative side, files of this format are quite large, and as mentioned already, it is not supported by desktop I.E.
  • The mp3 format – On the plus side, this format provides reasonably good sound quality (although it is lossy storage format) with small file sizes (it is a compressed).  Additionally, this format is supported by every modern browser except Opera.  On the negative side, there is typically a small lag when decoding the compression on this file - even if pre-loaded – and again as already mentioned, no Opera support.  Additionally, there are potential legal issues with using this format which although quite standard in the music industry, is proprietary in nature.  The good news for consumers is that several of the patents related to mp3 usage have already gone through one patent extension and the last of these remaining patents are due to expire sometime in 2015.  Although one or two patents related to mp3 are still enforced by two companies, this enforcement is ebbing and might not even be an issue except for high volume usages (and in these cases the financial demands for usage are not so unreasonable).  Caveat: Let it be understood that I am not a lawyer and not offering legal advice – use mp3 at your own risk.
  • The m4a aka ACC format – This is a variation on MPEG4 for audio files, a descendant of mp3.  There are several plusses compared to mp3: files are smaller, the sound is higher quality and usage is completely royalty-free.  The downsides are that support for this format is probably not quite as widespread as it is for mp3.  Also, I believe there is still a decode lag on this format.
  • The ogg format – This is a proprietary but license-free format that offers good quality and reasonable size files.  The downside is that it is only available on certain platforms: Chrome, Firefox and Opera.  Neither Internet Explorer nor Safari support it at this time.

If you have to choose one format, wav is a pretty good choice for small sounds and m4a (ACC) is a pretty good choice for large sounds and music files.  The mp3 format may also be a possibility (just an observation – follow it at your own risk).  However, be aware of the aforementioned caveats when choosing these or any formats.  The good news is, you can specify multiple formats.  This is easy and reliable if you put static tags in your html, and more difficult if using JavaScript.  The canPlayType method is used for this, but instead of returning true or false, it returns “probably”, “maybe” or empty string – go figure.  Another of the nice features of Howler.js is that you can specify an array of files in different formats for the same sound, and Howler.js will figure out which to play.  Of course, one problem in going with the multiple format approach is that you have to provide multiple resources, which is more hassle and not ideal on mobile devices with their limited storage space.

We’ll look at just one more concern – the issues with mobile Safari – and then finally move on to some actual code.  Mobile Safari has the following issues with playing sounds (this list is derived from a somewhat famous article by Remy Sharp on his blog – see link at bottom of page):

  • iPhones do not like playing too much audio at once, it gets very choppy.
  • iPads do not play more than one audio stream at once.
  • iOS will not preload the audio unless the user initiates the action.
  • There is about a 1/2 second delay before iOS is able to play the audio.  This is because the audio object (in iOS, not HTML5) is being created.

The list above can be condensed into two major problems:

  • Apple iOS / mobile Safari uses a singleton audio object to play sounds and switching between sound resources always incurs a lag while the backing audio object is being created and initialized.
  • A user must take an action in the UI before each sound can be loaded – this effectively means that there is no preload and you must suffer an additional lag to load each sound the first time it is played.

There is an approach that  helps to address these two problems: the use of a single sound file containing sound sprites (aka audio sprites).  The term “sound sprite” or if you prefer, “audio sprite”, is a derivative of the css or image sprite idea employed in game development.  Image are often packed together in single files known as sprite sheets.  These sprite sheets consist of multiple embedded images, which are in turn used as textures to give game sprites their unique individual appearance.  Placing sprites all in one sprite sheet results in better organization, better performance and better memory usage.  Similarly, a sound sprite is an embedded sound in a single larger file containing other embedded sounds.  You get some of the same benefits using this technique that are gained through the use of image sprites, but that’s not the best reason to use them.  the biggest reason that sound sprites are worth using is that they help surmount some difficulties experienced in playing sound in Apple’s mobile Safari browser.  Creating JavaScript code to use a sound sprite is no trivial matter (also see the above-mentioned Remy Sharp article for details on how to do this).  Fortunately, once again Howler.js can come to your rescue.  It provides an API for using a sound sprite in addition to providing APIs for using stand alone sound resource files – and don’t forget, it will use Web Audio if it is supported, which gives better results than HTML5 Audio.

Now, at last, we get to look at some code -  the first example is a Sounds object that relies on plain HTML5 code and the Audio element.  This Sounds object is in its own module, contained within an IIFE (Immediately Invoked Function Expression), and uses the revealing module pattern to expose functionality.  The object is stored in a single global app variable, making it ready for use anywhere within the app with no pollution of the global name space.  Take a look at the code below.

The gist of the code above is that five different sound files are loaded and methods are provided to play these sounds individually.  Each sound is assigned to its own dynamically created Audio element, with the src attribute of that element referencing the actual file containing the sound.  The preload attribute is not used here, since the default for the preload attribute is “auto”, and that is what we want.  This is the best shot at getting our sounds preloaded, but in reality, a preload of “auto” is only considered a request, and browsers may honor it or ignore it (e.g. mobile Safari ignores it).  I should note here that canplaythrough event that is used here as a means of knowing when a sound has been loaded is not perfect – at least not on some browsers.  In Chrome, if I specified a path to a file that did not exist, the canplaythrough event  still fired - though it fired almost immediately – I suppose because there was nothing to load.  To complete the explanation of this Sounds object, a reference to each audio element, and thus each sound, is stored in the sounds object as a property using the associative array syntax, with the property name being a short descriptive name for the sound.  This name is the argument value that is passed to the play method, denoting which sound to play.  I have used objects very much like this in small projects and apps and they work well for providing basic sounds.

Now we’ll look at a Howler.js version of this same object.  This implementation uses a sound sprite file, although as previously mentioned, Howler.js also supports the playing of stand alone files as the “hand-made” object above does.  However, Howler provides much more built in capability than the object above and it does so in only about 9K of code.  Take a look at the Howler version of a Sound controlling object below.

In the above example, there are four sounds embedded in one file – the loading and playing details all handled by Howler.js.  This file is borrowed from a JSFiddle example created by Aaron Gloege (see link at bottom of page). Note that for each sound, a starting point with the file and duration a duration (both in milliseconds) are specified.  When Howler.js plays one of these sounds, it seeks to the proper point in the file and plays it for the specified duration.  It is also worth noting that each embedded sound is surrounded by a small amount of silence (generally a second or two) which allows for some leeway in the precision of the audio playing mechanism.  Despite major internal differences, the API for the HSounds object is pretty much the same as the Sounds object API.  So I’ll not repeat a description of that.

This article is drawing to a close – I hope you found the explanations, the demos and the stealable code to be useful.  As promised at the start of the article, a small demo of a page that uses both of these objects can be found on Uberiquity.com, here.  In the sections below I provide other links pertinent to this article and also attribution for the remaining sound files (those other than the file I borrowed from Aaron Gloege’s JSFiddle).

Resources cited in this article:

Remy Sharp’s Audio Sprites article

Aaron Gloege’s JSFiddle Audio Sprites example

Howler.js Home Page

Using HTML5 audio and video (MDN)

 

Attributions (for sound files other than those used by Mr. Gloege):

  • The “1″, “2″ and “3″ sounds are being used under the  Creative Commons Attribution License (3.0) and were created by Margo Heston.  They can be found in a pack on freesound.org at http://www.freesound.org/people/margo_heston/packs/12534/
  • The shore sound and the ding sound are being used under the Creative Commons 0 License.

 

 

 

Getting Closure on JavaScript Closures

Leave a reply

“I’m not interested in closure.” – Larry David

Larry wasn’t talking about JavaScript when he uttered these words, but if he had been, I would have to disapprove.  Understanding closures is important and is expected of professional-level JavaScript programmers.  The proper use of closures adds useful variable and function hiding techniques to a programmer’s repertoire – on the other hand, an inadvertent creation of a closure can in some scenarios lead to a memory leak.  In this article, closures will be clearly explained and the useful effects as well as the potential unwanted effects of closures will be examined.

Closure can be a difficult concept to grasp.  In my early JavaScript days, I became aware of the concept but struggled to understand it.  Eventually, I stumbled upon some decent examples (there are many poor ones out there) and forced myself to study them until closure finally made sense to me.  So, I understand both “not getting it” and “getting it”, which in my opinion puts me in a good position to explain closure.  If it has been fuzzy or incomprehensible to you until now, this article should put an end to that.

We’ll be looking at four examples of closure. The first two are very similar to one another and both of these are stripped of any extraneous code. The third example is somewhat more complex because I am trying to use closure to demonstrate a real-world analog of something that is like closure. I tried to keep this example as simple as possible, but there is some risk that this additional complexity might dirty the waters and obscure the closure within. If you find Example 3 confusing, ignore it and consider only on Examples 1 and 2, which illustrate the same basic principle as Example 3.  Example 4, while important, can also be temporarily ignored if you are just trying to come to grips with closure – perhaps you can come back to Example 4 at another time if it does not make sense at first.  Any or all of these examples can be run from the following links: Example 1, Example 2, Example 3, Example 4.  It may or may not be helpful to see these small demos before walking through the code.   The same links will be also be provided at the end of the article.

So, what is a closure?  Closure is automatically enabled when one function is defined inside another.  In fact, when you see the word “closure”, it might be best to think of the word “enclosure” instead.  Why?  Because “enclosure” is a more appropriate word for what closure is.  If a function is defined inside of an enclosing function, then that inner function enjoys not only it’s own scope and the global scope, but also the scope of its enclosing function.  These are standard JavaScript scoping rules, but there is one more point to understand in order to grasp the idea of closure.  During run time, even if the outer enclosing function has executed and is no longer in context, if you have a reference to the inner function on hand, the inner function still knows about the scope of the enclosing function that invoked it. The inner function retains access to the variables and any other functions of the enclosing function.  It is important to remember that it is not the state of those variables at the time of the call that is preserved, it is the reference to those variables.  This is an important distinction that will be explored in Example 4, but for now we should focus on the most basic explanation of closure.

The example below should clarify the basic explanation of closure given above.  The actual JavaScript code that forms the closure consists of only a handful of lines.  However, the entire example is not very large and I think it will make the explanation easier to understand if both the closure code and the supporting HTML with other code is shown. (Note: Normally, good practice is to separate JavaScript from HTML, but for an example like this it is better to include them together.)

In Example 1 above, turn your attention to lines 8 through 16 – you will find there the hallmark of a closure: a function within a function.  The enclosing function, “makeGreeting”, has one argument named “who”, one internal variable named “greeting”, and one internal function named “GreetWhomever”.  Notice that the GreetWhomever function takes advantage of the scope of it’s enclosing function to utilize both the variable named greeting and the argument named who.  These variables don’t belong to the inner GreetWhomever function, but the scoping rules of JavaScript allow the inner function to see the variables and arguments of it’s enclosing function.  What we have here are the makings for a closure, but not the closure in action.  To see a closure at work, you can run the demo for Example 1.  Each button gives a separate greeting: one is “Hello World!”, the other is “Hello John”.  Let’s examine the code a little more closely to see why this is so.

Looking at the last line of the makeGreeting function, it can be seen that the definition of the GreetWhomever function is being returned.  Note that it is not the result of the function, but a reference to the function itself that is being returned. So, when the global variables “greetWorld” and “greetJohn” are being initialized, they are actually receiving a reference to the GreetWhomever function.  This is borne out by the fact that in the onclick handlers of the two buttons, it can be seen that parenthesis has been used in conjunction with the variable names in order to invoke them as functions.  Ok, so that is understandable, but what of the closure magic?  Look again at the initializion of the greetWorld and greetJohn variables.  In each case, the enclosing makeGreeting function is being called, but a different greeting recipient is being passed in each case.  The value of the greeting recipient is therefore present in the “who” argument of the makeGreeting function.  Upon examining the inner GreetWhomever function, it can be seen that this “who” argument as well as the value of the “greeting” variable of the makeGreeting function are being used by greetWhomever. We already knew that it could do so, because an inner function enjoys the scope of it’s enclosing function.  The really interesting thing is, once the greetWhomever function has been returned and stored in the two global variables named greetWorld and greetJohn, the makeGreeting function has already been executed and is “gone”.  You’d think it has gone out of scope – but it hasn’t, because it is a closure for the inner function.  The inner function still has access to the variables of the outer enclosing function, even though the outer function has already executed.  This is closure at work.

Now let’s take a look at Example 2.   I will only show the code for the JavaScript of this lesson.  The HTML for this example is the same as in Example 1.  In fact, the JavaScript is almost the same as well, though not quite.  Example 2 exists for two reasons.  First, it repeats the lesson that was exposed in Example 1, but in a slightly different way – hopefully driving the lesson home.  The other reason is that the syntax employed in Example 2 is a lot more common than the syntax employed in the previous example.

In Example 2 above, the inner function is an anonymous function – it has no name.  This is a syntax that will be much more frequently encountered in actual JavaScript code than the syntax employed in Example 1.  Nonetheless, the code in this example works exactly the same as the code does in that example.  The inner function still utilizes the enclosing function’s variables (i.e. argument “who” and variable “greeting”) after the enclosing function has executed and is “gone”. If you run the demo for this example, you will see that it behaves exactly the same as the demo for Example 1.

My goal for Example 3 was to come up with a real-world analog of closure, and use JavaScript closure to make the example work.  I wanted to come up with a real-world analog into the article to help cement what JavaScript closure is.  The example I chose was that of a letter from friends or family vacationing in Hawaii (snail mail is not quite dead, though we are getting close).  The idea is that the letter itself is enclosed in an envelope.  We open the envelope and read the letter, and the letter informs us that there is a also a small picture inside the envelope that we missed when we pulled out the letter.  Because of the reference to the picture in the letter, we fish the picture out of the envelope to have a look at it.  The parallels to closure may or may not be obvious, but I’ll point them out anyway.  The envelope is like the enclosing outer function.  The letter inside is like the inner function.  The letter refers to a picture that we also discover inside the enclosing envelop.  The picture is like the data that belongs to the enclosing function and yet can still be referred to by the letter. For this example, I’ll present the entire HTML and JavaScript that make up the example.

In the rather long example above, take a look at lines 9 through 27.  It can be seen that this is pretty much more of the same – a function within a function.  The enclosing function here is named “envelope”.  The inner function is actually a constructor function for an object called “Letter” – but it is still a function and the closure trick still works.  In this example, the only variable that the inner function uses from the outer enclosing function is the Image variable, “picHawaiiCoast”. Nevertheless, a closure is a closure and this example functions very similarly to the first two examples.

In one way, this real-world analog of an envelop with a letter and a picture enclosed does not match the reality of JavaScript closures.  With the physical objects we can open the envelope and pull the picture out – this is precisely what closures can prevent – direct access to the variables belonging to the outer function.  I tried to gloss over this and make the analogy seem close to the way closures work by saying that “we had missed the picture until the reference to it within the letter made it available”.  However, it is important to remember that in JavaScript, access to an outer function that is “no longer present”, is granted only through the reference to the inner function at hand.  The bottom-most button in the example demonstrates this. Now that you have been exposed to the code for Example 3, it might make sense to run it (see links at top or bottom of article) if you have not already done so.

Earlier in this article, in the paragraph in which closure was defined, I made this comment: “It is important to understand that it is not the state of those variables at the time of the call that is preserved, it is the reference to those variables”.  The purpose of the fourth and last example is to help explain what that means.  Example 4 provides a UI with two buttons – each button causes console output (accessible in Chrome via Ctrl-Shift-J, in Firefox via Ctrl-Shift-K and in IE via F12 – apologies to Safari and Opera users, I am unfamiliar with those).  One button is backed by code using a closure that makes a naive attempt to count from 1 to 3.  The other button is backed by code using a closure and an additional level of closure to fix the problem with the naive attempt.  If you were to run the examples and press each button in succession (naive, then non-naive) you would see the following output in the console:

Examine the code behind each of these buttons below.  (The minimal HTML needed to execute the example has been omitted).

Code behind the “Naive Count 1 to 3″ button:

The “naive” code above fails, outputting three consecutive lines of “Count = 4″, instead of the expected “Count = 1″, “Count = 2″ and “Count = 3″ on three consecutive lines.  Why?  Because the closure from which each function is referencing variables is the same closure.  Furthermore, the state of the count variable in that closure is such that count is equal to 4 when the functions are finally executed.  It makes no difference at all that as the individual functions were stuffed into the array, the value of count was 0, 1 and 2 respectively.

Code behind the “Count 1 to 3″ button:

The “non-naive” code above succeeds, outputting a count of 1, 2 and 3 as expected.  Compare the two sets of code above.  The “non-naive” successful code wraps the original inner function in a new function, passing in the value of the outer function’s count variable via an argument.  This works, because we have created a new, intermediate closure around each innermost function.  Study it and think about it until it makes sense.  If it doesn’t click for the moment, that is alright, you will still have made the most important mental leap in understanding closures if you comprehend Examples 1 and 2.  You can come back to this later when you stumble upon a closure bug like this and then this example will help you figure it out.  Similar problems can crop up when setting up event handlers, so keep that in mind.

So what are closures good for?  At the top of the article I promised that we’d delve into some useful features of closures.  I’ll cover two reasons here.

  • The first reason is that they are a great way of hiding variables and functions – i.e. making them private.  Only the inner function has access to this data once the outer function has executed.  This mimics the idea of private members in object oriented languages such as C++ and Java, allowing the construction of objects with both private data and private function members.  Example 3 is a case in point,  although a more useful pattern for creating a reusable object with private members would result if the enclosing function returned the inner “constructor” function instead of using the inner function to create a new object.
  • A second reason I will point out, though not discuss in detail, is that when using closures to define member variables for objects, no “this” reference is involved.  That is different than the syntax necessary when defining a constructor function with instance variables and methods.  That difference is important when using object methods in conjunction with things like event handlers, which reset the “this pointer” and can cause bugs in code when a method of an object is passes as the callback for an event handler.  That particular problem is non-existent when a closure was used to create member variables and functions for an object.

Are there any other problems that can occur if closures are not understood or go unrecognized?  In addition to the type of bug that Example 4 embodies, in some browsers and some scenarios, the formation of a closure can result in a memory leak.  This problem can often occur in conjunction with the establishment of an inadvertent circular reference due to the formation of a closure during event callback creation.  I am not going to attempt to explain this in detail here – it is a topic for an entire other article.  I will however, point you to this excellent article on JavaScript memory leaks, located on the IBM developerWorks site: Memory leak patterns in JavaScript.

Well, it’s time to bring this article to a close.  I hope that if you were “closure-challenged” (which is not uncommon), this article helped you get some closure on closures.  As promised above, here again are the links to the four examples discussed in this article: Example 1, Example 2, Example 3, Example 4.

 

 

 

 

 

 

 

Examining Underscore.js Search and Filter Collection Functions

Leave a reply

“Price is what you pay. Value is what you get.” – Warren Buffett

By any measure, Underscore.js is a great deal. Underscore.js is a tiny open source JavaScript utility library that packs about 80 useful and eye-opening functions into only about 5kb (minified and gzipped).  A significant number of these functions are applicable to collections.  In Underscore.js, the term “collections” can refer to arrays, objects, and array-like objects such as arguments and NodeList.  Follow this link to examine the Underscore.js documentation for these functions.  In this article we will be looking at actual usage for some of these functions.  You can find a demo/test page that runs these examples here.

A number of these collection functions are ideal for search-related applications. It’s interesting how many of the Underscore collection functions are reminiscent of SQL. If one were to look at the full list, one would find that about half of them have names and/or do things that are related to SQL select functionality, e.g.:

  • each
  • find
  • filter
  • where
  • findWhere
  • reject
  • every
  • contains
  • max
  • min
  • sortBy
  • groupBy
  • countBy

It is worth noting that the popular JavaScript MV* library, Backbone.js, proxies and uses many Underscore.js functions.  It makes particularly good use of many of these SQL-evocative functions for assisting programmers in the management of collections of Backbone Models.  The search functionality that this article examines, or analogs thereof, could just as easily be implemented in Backbone.js as it could via the more low-level Underscore.js.

There are small number of usage patterns shared by these Underscore.js collection functions.  We’ll be looking at four collection functions, chosen as being representatives of both the functionality and pattern usage differences that pertain to the functions in the above list.  We are going to begin by examining the _.where function, which has great functionality even though it follows a simple usage pattern.  Take a look at the code below.  (Note for programmers unfamiliar with Underscore.js:  As befits the name, all Underscore functions begin with an underscore (_) character, similar to how jQuery functions begin with dollar sign ($) character.)

The code above produces the following output:

In the test function shown above, note first the signature for the _.where function.  It takes two arguments, “list” and “properties”.  The first argument, list, is one that is found in all of the Underscore.js collection functions.  Recall that collection functions work on arrays, objects, and array-like objects such as arguments and NodeList.  The list argument can represent any of these things.  It is important to understand that the nature of the reference passed via the list argument will slightly alter the usage pattern for these collection functions.  In this particular test we are passing an array of objects named “testArr” as the list.  The other argument required by _.where is the properties argument, which must be an object containing one or more properties that are used as the where criteria, i.e., what to search for in the given list.  In the test case above we are passing an object containing two search properties – we are looking for things that are green and have a tail.  In the input list we have four objects, all of them containing color properties and all of them containing tail properties.  Of the four, only one of them – an iguana – is both green and has a tail.  As is to be expected, when this test is run, only one object is returned – the iguana object.

The next function we will be looking at is the _.each function.  I chose this function as one of the four because of it’s flexibility and because it is a good one to use in illustrating the full range of usage patterns that may be encountered when using the Underscore.js collection functions.  Take some time to really look at the two code examples for this function – if you can get through this part the rest of the article is down-hill.  Whereas the _.where function is fairly simple – taking only a list and a set of search criteria as its arguments – the _.each function is inherently more capable, but with less specified functionality at the outset.  In addition to the list argument that we have already touched upon in the previous example, the _.each function has an iterator argument and an optional context argument instead of a “properties to search for” argument.  The iterator argument represents a function to be passed and the optional context argument represents a “this pointer” context to be bound to the iterator function. The ability to reassign the this pointer for an object or function is a commonly used JavaScript technique.  An in-depth explanation of this technique is outside the scope of this particular article, however we will see the context argument in use.  The iterator argument concept is a different story.

In this discussion of the _.each function and in this article in general, we will be spending a fair amount of time examining different uses for an iterator function, as many of the collection functions have such an argument.  The basic concept of an iterator function is the same for all collection functions that use them – it is a bit of code that the Underscore collection function will call for each item in the given list argument.  The number and the nature of arguments that Underscore will pass to an iterator function varies with the particular collection function, as does the nature of the expected function return, if any.  Let’s go ahead and take a look at the code for the first of two _.each tests in the demo page.

The code above produces the following output:

In the test function shown above, note first the signature for the _.each function.  When calling _.each, we are passing a simple array of strings for the list argument.  The iterator function is defined on the fly, as an anonymous function.  The third argument to the _.each method – the context – is a reference to an object declared outside of the testEachInArray function. Lets look closely at the iterator function.  It takes three arguments – the Underscore.js documentation for the _.each method specifies this.  It has no return value.  Ok… but what is it doing?  The answer is, not very much.  It is merely printing to console the content of the three arguments for each iteration.  The Underscore.js documentation states  for the _.each method further states that when the list argument is an array, the first argument will be the value of the array element being processed for the current iteration, the second argument the index of that array element, and the third argument will contain the content passed as list (the entire array).

A major purpose of these _.each function examples is to show an iterator function in action – to give an idea of what sorts of things can happen when an iterator is being called.  In actual use, the iterator function passed to the _.each function would be doing some kind of work with each element in the array, as the _.each function iterated.  But what of the final argument, the context?  Note at line 19, the use of: this.contextValue.  The output of the function in the console proves that the this pointer for the iterator function has been set to the this pointer for the anExternalContext object, because contextValue prints out correctly.  Let’s take a look now at  the second _.each function example.

The code above produces the following output:

In the test function shown above, note that we are calling upon the same _.each function that we called in the previous test.  The difference here is that we are passing an object as the list argument, instead of an array.  This example is more or less the same as the previous one except that the usage pattern is slightly different because the list is an object this time.  Here we must make allowances in the iterator function for the fact that each iteration of _.each is working with a property of the given object passed as the list argument, instead of it being an element of a passed in array.  The Underscore documentation tells us that the three arguments passed to the iterator will (naturally) be a little different for an object passed as list than when an array is passed in the list argument.  Here, the first argument will be the property value being processed for the current iteration, the second argument will be the key for that value, i.e. the property name, and the third argument will again be the content passed as list, in this case an object.  The iterator function takes these differences into account (e.g. the use of JSON.stringify to get a string representation of the list object), but otherwise works the same as the iterator function worked in the first _.each example test.

The next function we will be looking at is the _.max function.  I chose this one because it is reasonably straightforward and representative of other similar functions (e.g. _.min, _.find), in addition to being very useful in its own right.  The iterator function is optional for the _.max function, but when used, its purpose is clear and it is easy to comprehend. Lets look at the first of two examples, one that does not employ an iterator function.

The code above produces the following output:

In the test function shown above, note first the signature for the _.max function.  It is the same signature that _.each uses, except that the iterator function is optional.  In this first example test of the _.max function, we are not passing an iterator.  There is no need for one, as the list we are passing is a simple array of strings and the _.max function needs no additional help to be able to iterate through and find the largest number in the array.  Lets look now at the second _.max function example usage, which does require an iterator function to be passed.

The code above produces the following output:

In the test function shown above, note that we are calling upon the same _.max function that we called in the previous test.  The difference here is that we are passing an array of objects as the list argument, instead of an array of numbers.  This example is similar to the previous one in that _.max is trying to iterate through the input list to determine the largest value in set.  However, the data is different here – both in content and in nature.  The _.max function cannot know on its own, the property name within the array of objects that it must access in order to determine the largest value. In some cases, each object might have any of several properties that would be correct.  Even in this simple test case, it is possible to pass the value of the person property instead of the value of the IQ property (the highest sorting person name would be the “max” value in that case) but we want to find the person with the max IQ in our example.  So, we create the anonymous function to help out.  The Underscore documentation for the _.max function states that the iteration function for _.max must take an argument representing the current object being iterated from the array of objects, and return the value of the property that _.max will use to cull the max value.

The last Underscore.js collection function that we will examine is the _.filter function.  It packs a lot of potential power, but requires the programmer to provide most of that power by providing an iterator function. You will find two example uses of the _.filter collection function below.  The first of these will be a simpler use case than the second.  Each of these two examples will be a little different from the previous examples in that an example is made up of two functions – one is a re-usable function and the other is the test driver for the function.  Let’s take a look now at the two functions that make up the first example use case for the _.filter function: simpleFilterLike and testSimpleFilterLike.

The code above produces the following output:

In the test function shown above, note first the signature for the _.filter function.  By now this pattern should look familiar.  In the scenario above, we are passing as the list argument a simple array of strings, containing phrases that will be searched.  We are also passing a non-optional iterator function that returns a result of true (per Underscore specification for _.filter) if a searched-for string is found with the currently iterated phrase.  We are not explicitly passing the searched for string.  A “likeCriteria” object is created within the body of the function that invokes the _.filter function.  Within this likeCriteria object, a “searchFor” property is set, containing the value that we will search for within the phrases.  We could have passed this likeCriteria object as the context and shared it’s contents with the iterator function that way, but there is no need to do so as the scoping rules of JavaScript already make the likeCriteria object contents available to the iterator function.

What is happening inside this iterator function?  For each iteration, the _.filter function is giving us a phrase to search in and we are doing so using the contents of the searchFor property in the likeCriteria object.  The iterator function is “teaming up” with the Underscore _.filter function by returning boolean true if the searched for string is in the phrase – effectively allowing the Underscore function to filter which of the array elements (i.e. which phrases) pass a truth test. Those phrases that pass the truth test will be returned in a filtered array that contains only the right contents from the original array – where “right” means that the searched for string was found in the phrase.  Now lets look at the second scenario, in which two more functions are used in a similar manner to the ones just examined to call upon the Underscore _.filter function to help do a search.

The code above produces the following output:

The two functions shown above are not very different from the first two _.filter leveraging functions we just looked at, there are just a couple of twists.  The first is that instead of a simple array of strings representing phrases, we are passing here an array of objects containing phrases.  The second twist is that we are employing two searchFor criteria, which means that this version of the “likeCriteria” object contains an array property instead of a property holding a single string.  Otherwise, this pair of functions works the same as the previous pair.

The main reason for providing this second example of how to leverage the Underscore.js _.filter function is that this example is much closer to a real world use-case for a utility filter function that returns information based upon matching “like” criteria.  In fact, a more robust and capable version of the “filterLike” function forms the heart of the search implementation for the main Uberiquity site.  You can test the Uberiquity search feature out if you like, by clicking on this Uberiquity Search link. If you were to go there, you could search for this very article by using the following search:  underscore AND search

How To Dynamically Swap External Style Sheets with JavaScript

Leave a reply

“There are very few things that surprise me.” – Judi Dench

Myself, I would not go as far as Dench – at least not in the world of Web development.  However, I will say that it isn’t everyday that I stumble upon something truly new (well to me) and delightful.  Nonetheless, not too long ago I discovered that it is possible to change external CSS style sheets for a running web page via JavaScript – i.e. dynamically, at will, after the page has loaded.  I confess I felt sheepish that I had not known this was possible.  Perhaps you didn’t know it either.  Read on if you wish and you’ll find out how.

Why is this ability to dynamically swap external style sheets useful?  There are at least three reasons:

  • In cases where a large number of individual CSS/style changes need to be applied all at once, this style sheet swap method might be faster to execute and easier to maintain.
  • The second reason is perhaps a specialized case of the general case stated above – this is a great way to implement dynamic theme changes that can be invoked by the user at any time.
  • The third reason is that this technique can assist with responsive web site design – i.e. changing the layout and sizes of element in a page to accommodate radically different screen sizes.  A more standard approach to responsive design relies on CSS media queries, which allows CSS to alter itself to accommodate different screen sizes.  Unfortunately, the sad reality of today is that many of the older mobile platforms (i.e. device, plus OS, plus mobile browser) do not properly support CSS queries.  Even on newer platforms, media query support can be quirky.  So one alternative approach is to substitute the technique being described in this article to allow for “responsive” CSS changes.  Instead of using media queries, JavaScript code can check the browser document size upon initial display and every refresh and then dynamically adjust font sizes, and specific DOM element dimensions by swapping in style sheets that have been created for best viewing at certain trigger sizes.

Actually accomplishing this feat is easier than one might expect – at the heart of it, there are only three standard, cross-browser DOM functions that need be employed for this purpose – removeChild, createElement and appendChild.  The basic idea is to remove one link element from the header of a page and add a new link element to replace it.  This methodology requires that two (or more) CSS files must already exist – no new CSS file is being created using this technique.  There are ways to dynamically create individual style sheet rules but this article does not cover that topic.  In any event – in my opinion – dynamically swapping entire style sheets is more useful.

To demonstrate actual swapping of external style sheets at run time I have built at a working demo page.  I will show every line of code and annotate how it works in the succeeding paragraphs, but it may be desirable to run the demo first.  Here is a link to the demo at my main site, uberiquity.com.  Check it out first or wait until after the explanation.  I’ll provide another link at the end of the article.

The demo consists of seven small files:

  • changecss.html
  • changecss.js
  • base.css
  • mono.css
  • red.css
  • green.css
  • blue.css

Only two of these files contain code and only one file, changecss.js, contains the actual code that enables the swap.  The base.css file contains all the non-swappable CSS used by the HTML for the demo, mostly formatting information that is non-color oriented – e.g. setting the sizes of things.  The other four CSS files represent themes.  It is these files that we can swap to change the theme of the demo page on the fly.  We’ll look at changecss.js first, then we’ll see how the single function in changecss.html calls the methods therein.

I like the names of functions and variables to be self-explanatory.  This means that to some people my function names may be annoyingly long.  I realize that this is a bit of a “religious thing” and not everyone likes the verbose approach – please forgive me if it rubs you the wrong way.  In any event, I list the content of the changecss.js file below.  It contains only two functions.

To make the swap, we need to first remove the existing external style sheet link.  For this purpose, we call upon the removeExternalStyleSheetLink function.  When first loaded, the demo page is linked to the theme CSS file named mono.css.  However, the demo user is allowed to swap in any of the other theme CSS files.  In order for this to happen, the demo first calls upon the removeExternalStyleSheetLink function to remove the link to mono.css, i.e.: <link id=”mono” rel=”stylesheet” type=”text/css” href=”mono.css” media=”screen” />.  Notice the rather unusual fact that the link has an id attribute – this is perfectly legal HTML (it’s just not done very often).  This id value of “mono” is the value that must be passed in the cssLinkId argument to the function.  The function uses it to get a reference to the DOM object of the external style sheet link that must be removed, and then does the removal by telling the parent of this DOM object to “remove me”.

Once the link to the original CSS theme file is gone, a new link element must be inserted into the head of the document to complete the swap.  For this purpose, we call upon the second function, createExternalStyleSheetLink.  The job of this function is to create a DOM object that will represent a link to the CSS file that is to be “swapped in”.  Like the removal function, the create function takes an id as an argument, because it is important to give this new link tag an id.  Giving it an id attribute makes it easy to reference it in case it too will be swapped out at some future time. The second argument, href, will of course contain the name of the CSS file that will be linked to (i.e. swapped in).  The function uses the standard DOM manipulation JavaScript functions createElement and appendChild to perform the work of creating the link object in memory and then inserting it into the proper place in the DOM. The proper place is in the head of the document, as denoted by the invocation: document.getElementsByTagName(“head”)[0].

Now let’s take a quick look at changecss.html.  I’ll list the entire file but the the main point of interest is the solo function named changeStyleSheet. Most of the rest of what is there merely exists to provide objects whose colors can be changed by a theme switch (i.e. proof of concept).  Note that I don’t necessarily advocate defining functions in HTML pages, but in this case, the function is quick and dirty and relies upon embedded page knowledge.  I’m doing a couple of other naughty things here, for instance, using a non-namespaced global variable.  Please bear in mind that I am striving for brevity and clarity of presentation – not necessarily trying to use best practices.

Before we look at the changeStyleSheet function, note again the link tag containing the id of “mono”.  That is the default theme that may be swapped out by pressing either the “Apply Red Theme”, “Apply Green Theme” or “Apply Blue Theme” buttons.  It is worth noting that the act of swapping the CSS files causes the page to radically change it’s appearance, but this does not cause a page refresh.

Because the functions in changecss.js have already been covered, there is nothing mysterious about the changeStyleSheet function.  We already understand how the removeExternalStyleSheetLink and removeExternalStyleSheetLink functions work, and the changecss.js function does little more than simply call them in succession.  The remainder of what the function does revolves around remembering the name of the CSS file for the current theme and displaying that information to the user.

The only remaining files to discuss are the CSS files – here is base.css.  This file never gets swapped out – which is of course the normal scenario for CSS files.  It performs a useful function in the demo by providing CSS that never changes, but its existence in the demo proves something as well.  The technique presented here is perfectly adept at “cherry picking” links – base.css remains undisturbed now matter how many times one swaps themes in the demo.

What follows after this paragraph are the listings of the four CSS files that could be considered to be “themes”.  There is nothing special at all about the makeup or structure of these files – they are just standard CSS files.  It is the JavaScript in changecss.js and the browser’s CSS engine itself that provide all the magic.

And there you have it – simple, sweet and powerful.  Here is that repeat link to the demo I promised I would provide.  If you haven’t yet done so, take a moment to play with it.