Simple Lightbox – The Road to 2.0: Modularity

Divide and Conquer
By Sol in Lab

Update: Simple Lightbox 2.0 has been released.  Get it now!

Why Modular?

In the overview of the changes coming to Simple Lightbox 2.0, I mentioned that the lightbox code had been entirely rewritten to be modular in nature.  This was not a trivial task, but there are a few reasons that make a modular approach an ideal option:

  • Organized – Code is grouped by purpose/use which makes it easier to find the necessary code when adding new features and maintaining current code
  • Flexible – Multiple instances of modules can be created, allowing multiple lightbox viewers with different configurations (options, themes, etc.) to be added to a page.
  • Extensible – New modules can be easily added to provide new features and functionality (even by 3rd-party plugins)
  • Consistent – All modules have a consistent API to safely access a component’s properties and functionality.  This means less issues due to small changes like internal name changes, etc.
  • Sane – I got tired of prefixing all methods with a namespace denoting their purpose (e.g. viewerResize(), itemShow(), etc.). Now methods can have simple names and can be easily called (e.g. viewer.resize(),, etc.)

Let’s have a look at the various modules


Everything starts at the Controller.  This is the command center that coordinates all of the other modules.  That being said, the Controller mostly initializes the other modules and gets out of the way for them to do their thing.

Modules that are managed by the Controller are called Components, and are actually what do most of the work in SLB 2.0.  All components share the same base and are then further customized to handle their specific functions.

The components are:

  • Viewer
  • Content_Item
  • Content_Type
  • Group
  • Theme
  • Template
  • Template_Tag
  • Template_Tag_Handler


A Viewer handles all display-oriented functionality for a lightbox, from navigation to animations to user-customizable options like UI text and overlay opacity.

Multiple Viewers can be added to the page, each with a different configuration, allowing different links (and groups of links) to be displayed differently from each other.

Viewers reference other components for its functionality:

  • The current Content_Item being displayed in the viewer can be accessed to determine the next or previous item to display (e.g. if it is part of a Group)
  • The viewer’s Theme controls what the lightbox looks like


A Content_Item represents an item to be displayed in a Viewer.  A Content_Item instance will be created for any link that is activated for SLB, and is used to access the item’s various properties that will be displayed in the Viewer (e.g. image, title/caption, description, etc.).

Items may be part of a Group that can be navigated through by the item’s Viewer, or isolated from all other items.

All items also have a Content_Type that defines properties and functionality for various types of content (image, video, etc.)


A Content_Type defines how properties are retrieved for a Content_Item as different approaches are required for different types of content (e.g. displaying an image compared to displaying a video).

Any number of Content_Types can be defined, allowing any type of content to be displayed by SLB.  Using a priority-based structure, custom Content_Types can even override default Content_Types to add new features for a specific type of content.


A Group is primarily a collection of Content_Items, allowing a Viewer to navigate through multiple items (e.g. a slideshow of related images).

There can be multiple Groups of items on the page.

A Content_Item can belong to a single Group (or none at all).


Plain and simple, a Theme controls how a Viewer looks when it is displayed.  Different Viewers can have different Themes to allow a different UI for each Viewer.

All Themes have a Template that defines the layout of the content to be displayed in the Viewer.


At its core, a Template is a bit of HTML with Template_Tags sprinkled to define how a Content_Item is displayed in the lightbox.  When requested, a Template will generate the final output using the properties of the Content_Item being displayed.

A basic template may look like:

<div class="container">
	<div class="details">
		<div class="nav">
	<div class="close">


A Template_Tag is a placeholder used in Templates that will be replaced with dynamic content for each item.  This allows full customization of what properties will be displayed for an item and how the properties will be displayed in the lightbox.

There are 2 default template tags (though custom tags can also be added):

  • item – Access the current Content_Item's properties
    • Examples
      • item.content: Item’s content (image, video, etc.)
      • item.caption: Item’s caption/title
      • The name of the group the item is in
  • ui – Insert UI elements into the template
    • Examples
      • ui.nav_prev: Button to navigate to the previous Content_Item
      • ui.close: Button to close the lightbox


A Template_Tag_Handler do the heavy lifting to control how Template_Tag in a Template is processed.  This allows any type of tag to be created for ultimate customizability.

There is one Template_Tag_Handler for each type of Template_Tag.

Simple, Right?

As you can see, breaking up the lightbox’s functionality into modules greatly simplifies working with the various components as the structure and relationships are quite clear.  The improved consistency and extensibility make the work well worth it.