vi·to

index · cv

Turn Balsamiq Mockups wireframes into clickable HTML imagemaps

Balsamiq Mockups is software for creating rough, low-fidelity wireframes with a hand-drawn, yet consistent look. I'm a big fan of the “drawn” look for wireframes, as I think it goes a long way towards ensuring the client understands what they’re seeing is unfinished: it keeps the focus on the interaction rather than the visual appeal.

At Optaros, we often need to create interactive prototypes to allow the client to walk through the site or software we’re proposing, or test an interaction. Sometimes these are clickable wireframes, sometimes these are more fully-realized mockups that need to preserve state through various interactions. We usually build these out in HTML and JavaScript, but this increases the fidelity of the wireframe, which risks the client misinterpreting what they’re seeing. I felt it would be useful to be able to produce an interactive prototype from Balsamiq wireframes, keeping the unreal look and feel but still getting the interaction testing that is so valuable. This tool is a first pass at this, and development is ongoing.

Balsamiq Mockups screenshot

bmml.py 0.051, 2009 November 25

Windows: Download the tool for Windows (.zip). Unzip it and double-click on bmml.exe to run.

Other: Download the latest source code (.zip). Requires Python 2.4 or 2.5 (use the command line if the GUI crashes on 2.6, it's a Tk bug), Tk (comes with Python), Mako for templates, PIL for image processing. Includes jQuery 1.3.2 and the maphilight plugin. MIT licensed.

Examples (click and view source)

Wireframe example screenshot Wireframe example screenshot
This wireframe illustrates the jQuery template, which includes the maphilight plugin to visualize the individual Balsamiq objects.

Wireframe example screenshot Wireframe example screenshot
This three-wireframe series shows a trivial example of an interaction using the jQuery template: a hover effect on the “Views” box in the upper left, plus being able to click through to see the changed sort order of the questions. Clicking again returns you to the first wireframe.

Usage

Run bmml.exe (or bmml.py) and it will ask you for your Balsamiq Mockups BMML files (you can select one or more) and the template you want to use (either a plain HTML image map good for basic click-throughs, or a more complex JavaScript scaffold using jQuery). It expects to find your exported PNG images the same directory as your BMML files. It will create a bmml_export directory alongside your BMML files. There, it will create an HTML 4.01 Strict document with a client-side imagemap for each BMML file, along with copying optimized versions of each PNG image. The plain HTML template defines one area for each object that has a “Link” property. Objects with multiple links (tab bars, etc.) are properly supported as of version 0.050. The jQuery template defines one area for each object in the mockup, hooked up with a basic jQuery scaffold. When the tool is done, an Explorer/Finder/equivalent window is opened into the bmml_export directory.

You can also specify the files on the command line, in no particular order. bmml.exe ..\projects\some_bmml_file.bmml "Plain HTML Clickable Image Map.mako.txt" will do what you expect, as will bmml.exe "jQuery Maphilight Clickable Image Map.mako.txt" ..\projects\one\mockup.bmml ..\projects\two\othermockup.bmml, creating a bmml_export directory alongside each BMML file, and both using the same template. No file navigation window is opened if the command line is used.

If you’re using the plain HTML template, you’re done. Open one of the HTML files in a web browser and you will be able to click through your mockups per the “Link” properties you set up.

If you’re using the jQuery template and the jquery-1.3.2.min.js and jquery.maphilight.min.js files were located alongside the template, they will have been copied into your bmml_export directory. Open one of the HTML files in your browser and you'll be able to hover over each area. The object ID is specified in the anchor tag, visible in the status bar. Balsamiq objects are sorted by the same front-to-back as in the original wireframe. Groups and locked status are noted in the comments for each object, but they aren't otherwise treated differently.

The rest is up to you. Cull out objects you don't need from the image map and the jQuery scaffold. Preload images for hover state swaps for increased responsiveness. Have an idea or need you'd like the script to auto-generate code for? Patches for things in TODO.txt? Did the Windows version crash and leave an error log?

v0.051 released November 25, 2009
v0.050 released November 21, 2009
v0.042 released November 10, 2009
v0.041 released October 13, 2009
v0.04 released August 18, 2009
v0.03 publicly released July 19, 2009
Released internally June 5, 2009
Idly conjectured on IRC April 29, 2009