JavaScript Gallery Builder

A JavaScript only method for sorting images within a gallery + lightbox popup

About this project:

Self Contained JavaScript Gallery Builder

This project is a continually evolving attempt at building a nearly self contained JavaScript gallery building toolset. With only a few additions to the HTML and CSS of a page, this project allows for a nearly plug-and-play style of gallery builder. The project also includes a lightbox style modal popup image viewer, and a mechanism for sorting images based on data tags.

The sample gallery above is built using simple images consisting of colored backgrounds, colored circles, and dates. I used these because they were easy to recognize and nothing more. The mechanisms by which the popup and sorting information operates will be discussed in detail further down the page.

Click any of the images to view them as a popup. The arrows to the left and right of the image allow for scrolling between gallery images without leaving the image popup format. The dropdown menus to the left allow for sorting the gallery images based on background color, circle color, and written dates. Multiple filters can be applied at the same time. The popup image slideshow scroll buttons will only switch between images that are currently being displayed (hidden images do not show up).

Technologies used:

JavaScript: This project focuses almost exclusively on JavaScript, a high-level, dynamic, weakly typed, prototype-based, multi-paradigm, interpreted programming language. Utilizing the universal implementation of JavaScript as the client-side web language of choice let me focus on creating a script that was contained in one file, and would easily react to user input without the need to reload the page. JavaScript's ability to manipulate HTML and CSS content on the fly using event listeners allows for image sorting mechanisms and lightbox style popups.

Technical Talk:

Works best when viewing code in JS Bin


Before I explain anything, do keep in mind that the names of the classes and IDs are what they are because makes sense for this working example. You may change them to whatever you like, but make sure the CSS and JS functions are changed as well.

The HTML itself consists predominantly of three parts. The first are the drop down menus used for sorting the gallery images, the second are the images in the gallery, and the third is the lightbox style modal popup.

The drop down menus are merely unordered lists set to show the inner options when clicked. Feel free to use <select> tags or radio buttons or whatever—I just liked the list option because it was easy to style.

The next section of html is a standard <div> tag with images inside. The only unique feature of this are the data attribute tags. These tags are used for the filtering system that I'll talk about in the JavaScript section of this page. The only exception to this is the data-name tag, which is used to connect to an array in the JS section that contains information about the image in the lightbox style popup.

The final section of notable HTML is the lightbox style popup modal. This section consists of a container div, a "Close X" popup bit of text (for iOS users) to help close the popup, an empty img tag which will have the clicked upon image inserted, an empty <p> tag for the image description to be inserted, and arrow icon buttons which will allow the user to scroll between images without leaving the popup. These will all be touched upon again when I get to the JavaScript section of the site.


The styling of the css is, for the most part, up to personal taste. The filter drop-down menus can be placed anywhere and made to look however you'd like. The same goes for the images displayed in the galleries. The only real locked in rules are in relation to the modal popup.

The modal relies on JavaScript event listeners to trigger the opening and closing (display block vs. display none), but we can discuss that later. The styling in this case is done with the .modal class, which is seen to start out with a display: none; so that it is completely hidden from view. When it is triggered/opened, the modal has a high enough z-index, in this case 15, so that it appears above everything else on the page. The div is set to fill the whole screen, remain fixed, and sit at 80% opacity, giving the rest of the screen a faded out appearance. The overflow-y: auto; feature allows for the user to scroll down (if the image is exceptionally tall), without the background webpage moving—it allows for scrolling of a fixed placement image. The inner pieces of the modal are also set to trigger the popUp animation when triggered. This quickly transforms the elements from nothingness to their full size, causing them to "pop up" when an image is clicked on.

The image itself is relatively standard. I find a block placement makes setting the "close X" text above and the title/image description below quite simple. But once again, you can pretty much style this part however you like.

The "close X" text (popupX) and the text below the image can be styled however you like. I find white text is easier to read against the dark background, but do whatever makes you happy. There's really nothing fancy about this styling.

The scroll arrows (#galleryLeft and #galleryRight) are fixed vertically in the center of the page, off to the left and right sides. They're also set to change color when :hovered over. It's straight forward stuff in this section.

The JavaScript

The first thing the script does is check for images within the "gallery" ID div. It cycles through them with a for loop and assigns a dataset attribute "arrayid = i" to each image. This becomes important later when scrolling between images within the popup interface. The loop also applies an onclick attribute to each gallery image, which triggers the "doOnClick" function.

Gallery Popup:
The gallery popup section starts primarily within the "doOnClick" function, under the Lightbox Popup subsection. As discussed in the CSS section, the popup modal's display attribute is swapped from hidden to block, so that it comes into view. The image source, text information, and arrayid dataset number are all passed to the popup, and placed within their correct locations to display.

The lightbox close onclick events both do the same thing. The window.onclick event swaps the popup's display attribute to none when clicking anywhere outside the image/text, removing it form view. This feature seems to have an issues with devices running iOS (presumably due to the modal object covering the background with a high z-index). The popupX.onclick event gives a second option to remove the popup that works on all platforms.

Gallery Sorting Filters:
The filtering system is based on the data-attribute tags attached to each image in the HTML gallery. Keep this in mind, because they are going to need to match or nothing will work.

The example is split based on background color, circle color, and the dates on the image. You can see these three data attributes in the HTML file on the gallery images up above. The script first collects all of the drop down menu classes and ids into variables and runs them through three for loops (one per filter category. This sets onclick events so that whenever an option is chosen it triggers the related category's write function.

The write function first of all simply sets the text of the <span> at the top of the drop down menu to be the same as the selected option. The function then applies the selected, related dataset attribute's value (ex. data-background's value if selecting an option from the background color filter) to a dataset attribute at the top of the drop down menu named "current." This function then triggers another function named "filterAll".

The "filterAll" function is used to both hide filtered out images, and allow multiple filters to be applied at once. Using a for loop, the function goes through each image in the gallery and removes the "hideImage" class. This is necessary in order to unhide images that were hidden by the filter (if already used). The function will then check the status of the dataset "current" attribute in the <span> (at the top of each filter drop down) to see if it has been set as something besides "showAll". If it is "showAll" then the function moves on and checks the next filter category. If not, the function checks to see if the dataset for this category (date, background, circle) does not match what is currently set for the "current" dataset. If they do not match, then the function hides the image by applying the "hideImage" class.

Popup Image Scrolling:
The image scrolling feature (toggling between the images without leaving the popup) starts out in the "doOnClick" function. Remember that stuff I skipped over at the start of the function when I was talking about the popup modal? this is that. The first thing the function does after clicking on an image is to gather all of the images with the "hideImage" class attached into a nodelist. This and the nodelist of all images in the gallery are then both converted into true arrays. The "imagesForGallerySlides" global variable is then set by taking the true array of all images, and filtering it so that only the images not present in the "hideClass" array are remaining. This array is the run through a for loop and each image is given a new arrayid dataset attribute. These new arrayids become very important later as they allow for the popup modal to know where it is in the gallery and which image is supposed to come next (when images have been filtered out).

Once the popup modal has been opened, event listeners are waiting for input from the user, which passes either a -1 or 1 to the "galleryDirection" function (left or right in the gallery list). This number is then taken and added to the current "arrayid" dataset value of the modal to create the "newArrayId" variable. This variable is then checked against the length of the visible images array and zero (making sure we do not scroll past the last or first image in the gallery/array) and looped around to the other end of the image array if necessary. When this is completed, the src of the modal image is set to match the imagesForGallerySlides[newArrayId].src (gallery of visible images). If this is all done correctly, then the modal's arrayid dataset attribute is set to match the "newArrayId' variable, so that further scrolling between images may occur. The final step in the function is to set the description of the image without having to trigger it from within the doOnClick function by matching the current "name" dataset value of the image to the array of descriptions.

The "arrayid" attributes are simple numeric markers attached to each image that can be quickly assigned, fed into arrays, overwritten, and rewritten on the fly without risking disrupting any other code running on the page (as rewriting classes or ids might). This gives the popup modal a quick and flexible means to know where it is in the gallery when scrolling using the arrow buttons. This is especially important when the images to be displayed are prone to changing (based on filtering).