Isaac Cambron


Back to blog

Introducing Timestack

Aug 27, 2012

This probably won’t render correctly in your RSS reader. If not, click through.


This is Timestack:

It’s a jQuery plugin I wrote that turns unordered lists into nifty timelines. Docs here. Code here. Check it out.

Why did I build it?

Timestack is a small library and didn’t take long to write, but I had a few thoughts about the process that I wanted to share.

When you build software for a living, you make a lot of compromises. You start with a vision of what you want to build, you get to work, and you run into obstacles. Maybe the technology you wanted to use doesn’t exist. Maybe it does exist but doesn’t work the way you wanted it to. Sometimes the right thing to do is to fix that technology or just build your own before moving on to the actual work. But usually that’s not the right move. Usually, you compromise your vision, make do with the pieces you have, make some quirky work-arounds, and move on. If you don’t, you’ll end up rewriting your entire stack from scratch to make every little part just right and you’ll never actually get anything done. You’ll have a bunch of (maybe) cool infrastructure for something that hasn’t been built yet. Knowing when and how to make this kind of tradeoff is part of being a good engineer.

One of the nice things about a personal side project is that it allows you to absolutely, totally ignore that whole last paragraph. You can compromise as much or as little as you want. And if you’re like me, personal projects are an awesome opportunity to solve problems totally tangential to your goal, getting distracted by problems you encounter solving those tangential problems, and so on into fractal oblivion. That’s just fun. That’s what a personal project is. If I had to actually deliver it, even to myself, it would be a job. Jobs are fine, but they’re not the best context for depth-first exploration.

Anyway, here I was trying to make a nice interactive resume for a simple “Hi, I’m Isaac. I build things.” website. I wanted a timeline that showed when I worked where, because I think that’s more interesting than a boring bulleted list. I looked around and there are a few components out there that do this:

After trying out Timeline (it is pretty), I decided it was too big and heavyweight— it’s a timeline, not an application framework. It doesn’t need themes or its own script loader. Importantly, it also didn’t really do what I wanted, partially because it imposes some constraints I don’t like, and partially because it just isn’t meant for my use case. Simile is similar, but unmaintained and worse looking. I wanted something really simple:

  1. It should turn some list items into timeline bars. No-JS fallback FTW.
  2. It should create an interval key (the times at the bottom).
  3. It should be able to do stuff when the user clicks on the timeline items. Note that I don’t want it to show me stuff; I just want a callback. Component does less = more flexibility for the user.
  4. It should be small, simple, and hackable. Libraries for handling simple things should be simple, and tweaking them should be trivial.
  5. It’s not important that it work in old browsers.

So I put aside the website and jumped down the rabbit hole.

Notes on building it

Since I’m terrible at UI design, I looked around and quickly found Matt Bango’s Pure CSS Timeline. It looks pretty good and the CSS is simple. It’s hand-cranked, though; the widths of the bars are just hardcoded for the particular times he needed. So all I had to do was write some code to generate those widths. I also added colors, because why not?

Some things I think I know now:

  1. The look and feel of web UI widgets should be customized by the user through CSS. CSS already gives you inheritance, overrides, and all that jazz. Just keep it simple and tell your users to override the CSS you ship. Easy.
  2. Give widgets a width of 100%. The user can decide how big to make the container box.
  3. Go for cheap extensibility over configuration. Instead of adding a whole bunch of flags into the options list, I just put the functions I wanted to make customizable into the options defaults and let the users override them.
  4. When dealing with tricky spacing problems in HTML, use box-sizing: border-box. It’s takes away that problem where you need to set the div width to realWidth - border - padding, which would have been really painful here. In fact, I’m increasingly convinced that border-box should just be the default browser behavior.
  5. If you need to work with dates and times in JS, you should use Moment. It’s just more pleasant than dealing with native dates and times.

If you want to know more about Timestack itself, definitely go here.