JavaScript production notes

A recurring issue in projects where several people work on the same HTML, CSS, and JavaScript files (almost all projects for me) is how to make your co-workers aware of any special circumstances that may apply to the current project.

Some people use comments within the HTML or CSS file, others use Basecamp. At the office we've been using both of those methods, and they work ok. But when I read Andy Clarke's 24 ways article A Message To You, Rudy - CSS Production Notes I instantly liked the idea of using markup to add notes to the actual HTML templates and displaying them on demand with a little CSS trickery.

The original, CSS only solution

When trying out the demo Andy provided I noticed a small problem in Safari. The name associated with each note is displayed twice after you have hovered over the note. After some bug hunting I fixed the problem by adding display:block to one of the rules:

  1. ol#notes blockquote:before {
  2. display:block;
  3. content:" "attr(cite)" said: ";
  4. margin-left:0;
  5. font-weight:bold;
  6. }

While testing this idea on one of my current projects I thought that the dimmed display of the notes wasn't positioned quite where I wanted it to be, so I moved it just a little. I also changed its positioning to fixed to make it visible even if you have scrolled down the page a bit:

  1. ol#notes {
  2. position:fixed;
  3. opacity:.25;
  4. z-index:2000;
  5. top:-305px;
  6. left:0;
  7. }

What about using the keyboard?

Ok, those changes make it work a bit better for me, and I could have left it at that. But I started thinking that it would be nice if you could bring up the notes from the keyboard, without having to mouse over the dimmed note container.

The first thought that crosses your mind may be to add an accesskey attribute to the notes element. Nice thought, but only links and form controls can can have accesskey attributes.

So I guess it's JavaScript to the rescue.

The modified, JavaScript + CSS solution

To make it possible to bring up the notes by using the keyboard only I wrote this little script (RJtn.js):

  1. var RJtn = {
  2. containerId : 'notes',
  3. triggerKeyCode : 27, // Escape key
  4. activeClassName : 'visible',
  5. oContainer : null,
  6. init : function() {
  7. if (!(document.createElement && document.getElementsByTagName && document.getElementById(RJtn.containerId))) return;
  8. RJtn.oContainer = document.getElementById(RJtn.containerId);
  9. RJtn.addEvent(window, 'keyup', RJtn.toggle);
  10. },
  11. toggle : function(e) {
  12. var event = (!e) ? window.event : e;
  13. if (event.keyCode == triggerKeyCode) {
  14. RJtn.oContainer.className = (RJtn.oContainer.className == RJtn.activeClassName ? '' : RJtn.activeClassName);
  15. }
  16. }
  17. /* Utility function removed for brevity - download the full script before using */
  18. };
  19. RJtn.addEvent(window, 'load', RJtn.init);

When the specified key combination is pressed, a toggle function that shows or hides the notes container is run. The default is to run when the esc key is pressed, the id for the container element is notes, and the class name that makes the notes visible is visible. Change the settings as needed.

Another advantage this has over the CSS only solution is that the notes can be completely hidden until you bring them up by pressing the key combination. I left the notes container partly visible in my JavaScript production notes demo though (and please excuse my lame attempt at being humorous in the notes).

Since this is meant to be used during development I have not done a lot of browser testing. It works in Firefox, Safari, and Opera, which is good enough for my purposes. I have not tested this in IE. At all. If you're using that as your main development browser I think it's about time you tried some of the alternatives.

Further improvements

When I showed this to one of my co-workers, he was very skeptical. "Are you telling me I need to write all that markup to create a note? And insert the date and time? Forget it, it's too much work. I'd rather use Basecamp." And I had to admit that maybe he is right to some extent. I think it depends on how you use this though.

One way of improiving this technique further (that I don't have the time to look into right now) would be to create a bookmarklet that lets you add notes and store them on a server, and then use a bit of server side logic to write the appropriate notes to each site. That could make creating the notes quicker, easier, and thus more likely to happen.


Update: The demo now uses the esc key to toggle the notes on and off. It works fine in the browsers I have tested in (Firefox Win + OS X, Opera Win + OS X, Safari). The remaining bug is Safari's extremely weird display of the names. Finding a fix for that will have to wait until another day though.

Posted on December 18, 2006 in JavaScript, CSS