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.

Thoughts?

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 CSS, JavaScript

Comments

  1. This looks very nice, and I appreciated your stab at humor. he.

  2. Does this not fire off Ctrl+N and open up a new Firefox window for anyone else? It does open up the drop-down in the original window, but its not all that useful when focus automatically goes to the new window just opened.

  3. Quando você executa a rolagem, ele não sabe qual das barras deve rolar primeiro, a da página ou das notas, fica uma coisa confusa. E o shift+ctrl+n não funciona no Opera 9.10, ele abre uma nova aba!!!

  4. Works really nicely, but I agree with Rich Waters. The choice of shortcut key is rather poor, since Firefox (v2.0 for me) fires off a new window with the contents of the current tab, then promptly removes the that tab from the old window, preventing the notes from ever dropping down. Perhaps a different key combo could be used, and this would be much more handy.

    Great idea though, and cheers on the presentation, it’s top notch.

  5. December 18, 2006 by Roger Johansson (Author comment)

    It’s weird though that the key combo does not open a new window for me when I try this in Windows (which I had neglected to do). I’ll change it to something else.

    I also noticed that there are still problems in Safari that I did not see when I tested this locally. Weird.

    Back to bug hunting.

  6. That’s interesting. Obviously it’d come out before handing the project over but I can just hear the client’s objection if seeing the project before that time. ;)

    I wonder if it’d be of value to simply just attach a development page the project’s team could turn to for such information/discussion. It wouldn’t be included in the navigation, but could be added as a sticky link on all pages leading to a specific page bookmark on the development page depending on what page it’s accessed from. This might create a nice development record that could stay with the site (removing the sticky link of course).

    Or, if there’s a login on the site in question the sticky link could stay and be available to certain users (first development team members, then the web master after turning it over).

  7. December 18, 2006 by Roger Johansson (Author comment)

    Ok, I found a typo in the script that prevented it from working in Safari. I also changed the activation key to “escape”, which seems to work fine in Firefox, Safari, and Opera.

    Mike: Yes, there would likely be some odd questions if the client were to see this, which is why I think it may be a good idea to hide the notes completely and only bring them up with the keyboard.

  8. IE6, notes show up before I press the key. Also, you could just use php/java, get user’s ip, and if it’s in your firewall, serverside include the notes file. That way people outside can’t see your notes with view source.

  9. IE6, notes show up before I press the key. - me

    Lol. I Need to read more carefully. I missed this:

    I left the notes container partly visible in my JavaScript production notes demo though

  10. oops! The escape key does not work for me in firefox linux. All it does is stop the page loading if it still is. Charset/encoding problem?

  11. Not to want to rain on the parade, but for years in about 3 companies comments in CVS or bugzilla did exactly the same job for me without having to add extra markup. Then again, I haven’t worked in Brochureware companies or on sites that were not CMS driven for a while.

  12. When I use the “tab” key on Firefox the notes show up too! Of course they disappear once I have moved the focus to another area on the browser window.

  13. December 19, 2006 by Roger Johansson (Author comment)

    I’ll have a look at that Linux problem ASAP, probably in a day or two, as well as try to figure out why the tab key apparently brings up the notes in some Firefox configurations.

    Chris: If you have CVS available and your entire team is comfortable using that, fine. This is just another option that may work better in some cases and not at all in other cases. Blame Andy for the original idea ;-). And for the record I haven’t worked on a brochureware or non-CMS driven site for a long time either.

  14. I think add Microformats, It will like so good!

  15. I could definitely see this as a server side include that automagically quit being included on the live server (unless, say, a querystring variable was passed). I know using PHP, it’d be possible to easily put the notes file and the CSS file on a remote server. That way, all the notes would be in a central place and global if using a single include file. Using your bookmarklet idea, you’d also have access to certain variables, like page names, on the live server that could be put into the note to give visual context.

    I’ve never used any notes system except for putting notes on CVS commits, but I could see this sort of thing working well for the poor / DIY set.

    That probably takes the simplicity of the idea and throws it out the window, but I guess maybe the simplicity thing was ignored when you added JavaScript toggling.

  16. very cool

  17. A nice idea, but plain old comments seem to work fine for us :) Plus we have CVS as well. I think the having to remove the notes before going live is one more step that someone can easily forget in a production environment, especially if a job needs to go live quickly.

  18. December 19, 2006 by Rob E.

    Nice idea but adding notes has to be in a more automatic way. Maybe something similar to subversion.

    When you use the tab to switch between links in Firefox the notes window will appear when it gains focus. Is it how it’s suppose to work?

    The esc key seems to work in Linux Firefox just fine for me.

    //Rob

  19. Works for me and I really dig the idea.

    Adding notes via the interface would be ideal. An ‘add note’ shortcut key, with a simple form that submits via ajax. hmmmm I like.

Comments are disabled for this post (read why), but if you have spotted an error or have additional info that you think should be in this post, feel free to contact me.