adamlogic

In part 1 last month, I introduced a common UI scenario - dynamically showing and hiding form fields. The initial implementation for this functionality left much to be desired, though. The rules for which fields to show and hide were intertwined with the implementation of those rules, making it difficult to read and maintain. My goal in this part of the tutorial is to extract those rules into a JavaScript DSL (domain-specific language).

I should note that I regret using the term “metaprogramming” to describe what I’m doing here. Metaprogramming is becoming a bit of a buzzword that doesn’t have a clear definition. The most common definition I run across is dynamically generated code, or “code that writes code”. That might be technically correct - I have no idea - but that’s not the definition I subscribe to. I recently read The Pragmatic Programmer for the first time, and they describe metaprogramming as programming with metadata. Metadata is used here in the loosest sense, meaning any data about how your program is supposed to run. So the idea is basically to separate the details (or metadata) from the implementation. As I mentioned previously, I prefer to think of this as separating the “what” from the “how”. Okay, enough jargon. Let’s write.

The hardest part of writing anything is knowing where to begin. For writing a DSL, I recommend starting out by thinking about the vocabulary used to describe your domain. Sometimes this is different depending on who is describing it, be it a programmer, user, business analyst, etc. Before making that assumption, though, stop and think if it must be the case. Why do all of these groups of individuals use different vocabulary when talking about the same thing? Isn’t that just a recipe for miscommunication, where true meaning gets lost in translation?

Instead, make an effort to find a vocabulary that works for all parties involved, so no translation is necessary. Often, this common domain vocabulary can be found in your specs/requirements.

show us-state when country is “United States”
show province when country is “Canada”
show Brutus when state is “Ohio” or “Michigan”

The requirements from part 1 are exactly what I’m talking about. Our DSL should stick as close to this language as possible.

Now, we could use this language verbatim. It’s certainly not executable JavaScript code, but we could put it in a text file, read it in and parse it with JavaScript. While that’s certainly possible, I don’t find it desirable. The code will probably be overly complex, and since the DSL is just plain text, it gives the impression of being as forgiving as English. English is very forgiving of small grammatical variations, but since we’re going to be parsing it as data, it needs to adhere to a set of rigid rules.

I prefer to write DSL’s that are actually executable code. Since they are written in a programming language, it is clear right off the bat that there are strict rules to be followed. The bad side of this is that a non-programmer probably won’t be able to write with our DSL. In practice, though, I don’t find that to be a realistic goal. If a programmer can write it, but *anyone* can read it (and perhaps modify it), I’m happy.

So how do we take our requirements and make them executable code? This is probably the hardest part, and very subjective. Two recommendations for doing this in JavaScript: you can chain methods together to create a sentence-like construct, and be daring with method names. Here’s what I’m talking about:

show("us-state-field").when("country").is("United States");
show("province-field").when("country").is("Canada");
show("brutus").when("us-state").is("Ohio,Michigan");

On its own, a method name like “when” or “is” would be ridiculous. But within the context of a DSL where methods are chained together, it makes perfect sense.

This is obviously just the beginning of our form behavior DSL. We’ve defined what we want it to look like, but we haven’t touched the implementation. I’d like to keep my articles relatively brief, so I’ll dive into that in part 3.

Ryan Johnson over at Livepipe has taken my Form.Behavior DSL to the next level. Check out his Event.Behavior library and prepare to be impressed. His implementation is quite a bit different, and he has added some very cool features such as passing functions as parameters and chaining conditions with “and” and “or”.

Fortunately for you, he is less gun shy than I am about releasing his code to the masses. Maybe that will change for me, but right now I’d rather get some things cleaned up and more thoroughly tested in my own library before too many people try to use it. I promise that I definitely will be releasing my code here soon, but until then, be sure to give Ryan’s Event.Behavior a try.

Last week, I gave a presentation at the Columbus Ruby Brigade meeting about metaprogramming JavaScript. Although I posted that presentation here, the slides were short on text, so I thought it would be more helpful if I wrote a series of tutorials to discuss these concepts. Also, I want to take my example a bit further with more extensions and refactoring.

But before we dive into what metaprogramming is, why it is important, and how we can bring it to life in JavaScript, let’s start with an example that we can build on throughout the tutorial: Say we’ve got a really basic form with select boxes for country and state, and we have a requirement to only show the state when the selected country is “United States”. [example]

Event.observe(window, "load", function() {

  Event.observe($("country"), "change", function() {
    if ($F("country") == "United States")
      $("state-field").show();
    else
      $("state-field").hide();
  });

});

The code I have used to implement this behavior is pretty basic, but it does use a bit of Prototype that I should explain. If you’re a Prototype guru, you can safely skip this paragraph. 1) Event.observe is Prototype’s version of the addEvent method every JS developer has in their toolbox. 2) The dollar-sign method is a shortcut for document.getElementById, which is handy since I seem to do this *everywhere*. 3) $F is a similar shortcut which grabs the current value of any form element. 4) One of the many things that Prototype provides is a set of extension methods available on all HTML elements - show() and hide() are two examples of this which simply modify the “display” style property of an element.

This code works just fine, and there is certainly nothing wrong with it for such a simple requirement. Unfortunately, things get hairy as requirements change. Let’s see how our code scales when we want to do the following:

add province field
show province when country is “Canada”
show state when country is “United States”
show Brutus when state is “Ohio” or “Michigan”

Check it out in action: [example].

Event.observe(window, "load", function() {

  Event.observe($("country"), "change", function() {
    var country = $F("country");
    if (country == "United States") {
      $("us-state-field").show();
      $("province-field").hide();
    } else if (country == "Canada") {
      $("province-field").show();
      $("us-state-field").hide();
    } else {
      $("us-state-field").hide();
      $("province-field").hide();
    }
  });

  Event.observe($("us-state"), "change", function() {
    var state = $F("us-state");
    if (state == "Ohio" || state == "Michigan")
      $("brutus").show();
    else
      $("brutus").hide();
  });

});

Using the same style of event handling and field checking, I have attempted to meet the new requirements. Unfortunately, we have several problems. First, the code has two bugs: everything is shown when the page initially loads, and hiding the state field doesn’t automatically hide Brutus. I refer to the latter as the “domino” bug, since fields that are dynamically shown and hidden will create a domino effect if other elements are dependent on them. Knowing that these bugs exist, let’s put them off for a just a bit.

Our second problem in the code is readability. I’d like to be able to glance at the code and instantly know what it’s trying to accomplish. I’d like to be sure that I haven’t left out or misunderstood any requirements. When a requirement changes, I’d like to know exactly where my code needs changed. And when I make those changes, I’d like to have confidence that I’m not breaking something else. This is where the concepts of metaprogramming come into play.

The Pragmatic Programmer describes metaprogramming as pulling the details out of your code and into metadata. Often this metadata comes in the form of a configuration file or some other data source, but there is no reason it can’t be executable code, as long as you enforce a clean separation of the “what” and the “how”. The idea with this approach is to write your code with a vocabulary that mirrors your problem domain (the “what” you’re trying to describe). This kind of mini-language is where we get the term “domain specific language”, or DSL.

Now, in our case, the details - or the “what” - are the actual rules for when to show and hide form fields. Right now we have the rules intertwined with the implementation of those rules, and we have felt the pain from it - pain that will only continue to worsen as requirements change and features are added. What would be great is if we could pull those rules out so we can modify them independently of the implementation. What would be great is if those rules were written in a language that looks more like our problem domain than JavaScript. What would be great is if we built a DSL for dynamic form behavior.

That’s exactly what we’ll do… in part 2.

Here are some great resources to follow up on my presentation:

Dan Webb’s presentation on metaprogramming JavaScript can be found at the bottom of this post. A bit different approach than I took, but very cool stuff.

David Black discusses the unnecessary distinction between “programming” and “metaprogramming”. I couldn’t agree more.

In this edition of the Ruby on Rails Podcast, Geoffrey Grosenbach discusses metaprogramming with Glenn Vanderburg. This was actually the first time I had ever heard the term, back when it was “big and scary”. Glenn put it into terms that really made sense, and got me interested in exploring the concepts in my day-to-day work.

Russ Olsen walks through a two-part series on building a DSL in Ruby.

Jay Fields discusses various evaluation options in Ruby, which can be very helpful when building a DSL.

Update: Part 1 of the tutorial is now posted.

Here are the slides from my CRb presentation last night.

I think it went pretty well, especially considering it was my first real technical presentation like this. I certainly learned a few things, like not to take unnecessary shortcuts in my code, because I *will* get called out on it. If you saw the presentation and have some feedback, please send it my way via the comments. Also don’t be shy if you have any questions.

I’ve got some other JavaScript goodies I’ll be posting soon. I also plan to write this presentation up in more of a blog/tutorial format in the next few weeks (with complete example code), so stay tuned.