Skip to main content
IAM vs. CIAM CIAM Buyer's Guide Contact Us
Janrain respects your privacy and will treat the personal data you choose to share with us in accordance with our privacy policy.
 

Finally: A Free and Open Source jQuery Minimap Plug-In

By Luc Perkins | Posted on November 26, 2013

Blog Banner

Single-page interfaces are nice for a variety of reasons: you don’t have to click between pages to get what you’re looking for, which makes it far easier to orient yourself; you can utilize browsers’ search capabilities more readily; and you can take advantage of UI helpers like accordion interfaces. It’s no surprise that such interfaces have become dominant with the rise of thick front-end JavaScript frameworks and CSS pre-processors.

The Problem: Cognitive Overload

As we were designing our new Janrain documentation portal (which will be available to the public in early 2014), we actively sought to implement single-page interfaces whenever possible, for precisely the reasons listed above. In our current documentation portal, we have literally hundreds of separate HTML pages spanning a wide variety of domains, from our mobile SDKs to implementing Janrain social login to SAML integration. It’s a ton of material.

For our new documentation portal, we decided to cut down on the total number of separate pages by packing more material into each page. The problem is that that kind of process can lead to unmaintainable information overload on some pages that end up with hundreds of lines of text and dozens of headers and tables and images. When this happens, the potential benefits of a single-page interface simply vanish. Users don’t know where they are on the page, and their experience suffers.

The Solution: Visual Minification

In response to this dilemma, I designed a jQuery plugin that I call Minimap. It essentially shrinks a particular DOM element (such as the main page container) and compacts it into a single vertical column that spans the page from top to bottom. As you scroll up and down the page, the Minimap shows an exact replica of the page in miniature and darkens out the section that you’re currently viewing. In our documentation portal, it looks like this (this example is taken from our future RESTful API docs):

You’ll notice that on the left side of the page there’s an accordion interface that will take you to different places in the middle column (corresponding to different portions of the overall REST API). For a live demonstration, this page has a functioning demo. To turn on the mini-map, click on “Toggle the Minimap” in the upper left-hand corner and you’ll see it appear on the right side of the screen.

Another thing to notice: as you toggle the Minimap on and off, the value of the miniMapActive variable in local storage will toggle between true and false. That means that the user’s preference for having the Minimap turned on or off will persist through page refreshes and sessions.

Basic Implementation

Under the hood, Minimap is fairly complex, although pretty lean as far as jQuery plugins go. On the implementation side, I chose to keep things neat and simple by offering only a few available functions.

Most importantly, turning a DOM element into a minimap can be done in two ways. The simplest way is to simply run the minimap() function on a specific element that you’ve selected:

$('#body_column').minimap();

The other way is to pass the element into the plugin as the body_col option, which specifies which DOM element is to be used:

$.minimap({ body_col: '#body_column' });

The advantage of doing things this way is that you can centralize the configuration of the minimap in one place. Here are the other available options:

  • map_col — Specifies the custom element into which the map will be drawn. If this is not specified, the following element will be inserted before the body_col element:
    <aside class="map_col"></aside>
  • toggle_btn — The DOM element that is used to toggle the map on and off
  • draggable — A boolean that specifies whether or not jQuery.ui.draggable tools should be used
  • scrollto — A boolean that specifies whether or not jQuery.scrollTo is used to animate scrolling
  • map_header — Customized content to place in the header of the map column (for example a title)
  • minimap_opacity — Enables you to provide a value between 0 (totally opaque) and 1 (translucent) for the Minimap itself (default is 1)
  • minimap_left_border — Specifies what kind of border (as a raw CSS value) for the boundary between the Minimap and the body of the page (default is none)

And so we would do the following if we wanted to make a div with the ID container into a Minimap (squeezed into a div with the ID minimap), using an element with the id map_toggle as a toggle button, is both draggable and uses the jQuery UI scrollTo capabilities, and has a thin, black border on the left side:

$.minimap({
map_col: '#minimap',
body_col: '#container',
toggle_btn: '#map_toggle',
draggable: true,
scrollto: true,
minimap_opacity: .9,
minimap_left_border: '1px solid black', });

And if we wanted to put a header that simply said “Minimap” in an h1 element, we’d simply add this to our attributes hash:

$.minimap({
  ...
  map_header: "<h1>Minimap</h1>";
});

And once we’ve targeted the minimap element, the rest will be done for us. There’s no need to customize the element with CSS, as its dimensions will be calculated for you. The only “customization” of the element that is necessary is making the element fixed and have its height set to 100%, like so:

#minimap {
position: fixed;
height: 100%;
}

And if the JavaScript customizations on offer don’t cover your use case, then styling the HTML elements in play by hand is always a possibility.

Activating and De-Activating the Minimap

There are three basic functions available for the minimap element: show(), hide(), and toggle().

If you want to make the Minimap always appear on page load, you can simply wrap the show() event into your jQuery .ready callback (assuming that your Minimap has already been appropriately configured):

$(document).ready(function() {
$.minimap.show();
});

To make the Minimap appear for good when a button is clicked (at least until refresh):

$('#minimapButton').click(function() {
$.minimap.show(); // or, alternatively, $.minimap.hide() or $.minimap.toggle();
});

Caveat Emptor

The most important thing to know about the Minimap plugin is that it may impact user experience—perhaps negatively—in ways that are difficult to mitigate. Because a Minimap has the same status in the DOM as the element that it’s mimicking, any text that is contained within it will register with the browser as showing up twice, which will obviously impact users’ search results in ways that they probably won’t expect when they visit your site. This is unfortunately unavoidable given the nature of the DOM.

Also unavoidable: the Minimap plugin will not work in browsers that don’t support CSS scaling transforms, e.g. Internet Explorer 8 and earlier and Android 2.3 and earlier. If you’re using modernizr or a similar tool, its best to hide the Minimap (using html.nocsstransforms), or not load it altogether on these browsers. For example:

Modernizr.load({
test: Modernizr.csstransforms,
yep: [
// only load the minimap script if you can use it!
'jquery.minimap.min.js',
function() { $.minimap(); }
]
});

Conclusion

The Minimap plugin is an easy and intuitive way to have it both ways, i.e. to include a lot of information on a single page and to provide users an elegant way to orient themselves within the page’s contents. The code is on GitHub, so please feel free to submit issues and pull requests!

Popular Posts

About the author